Win a copy of The Little Book of Impediments (e-book only) this week in the Agile and Other Processes forum!
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

Code Conventions

 
Brunno Silva
Greenhorn
Posts: 8
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
The Code Conventions declares:

All source files should begin with a c-style comment that lists the class name, version information, date, and copyright notice:


SHOULD is not a MUST, so do I really need to create beginning comments in all my source code? Also:

Two blank lines should always be used in the following circumstances:

Between sections of a source file


So, do I need to put two blank lines between the package statement and the import block (and another two between the latter and the class definition)?

No code example (even in the Code Conventions itself) seems to fulfill the above rules.
 
Brunno Silva
Greenhorn
Posts: 8
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
May you help me with my doubts?
 
Marcelo Camargo
Ranch Hand
Posts: 43
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Bruno,

I am not starting any file with this comment. As you sad, you should not you must. I am using these comments as implementation comments, and only when necessary.

Marcelo.
 
Jim Yingst
Wanderer
Sheriff
Posts: 18671
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
[Brunno]: No code example (even in the Code Conventions itself) seems to fulfill the above rules.

Did you look at the part labeled Java Source File Example?

The code conventions document never really says what a "section" consists of. I see no reason to assume that the package statement and import statements are considered different "sections". I think that if a file is long enough that you think it would be useful to introduce some additional blank lines and comments to help the reader understand it, the coding standard is telling you to use two blank lines for this purpose. If you don't feel the need to break your source file into sections, then don't.

As for "SHOULD is not a MUST" - true. However if you only do the things you MUST do, you may not get as good a grade as if you also do the things you should do. This may depend on the grader - some graders may not take off any points for this sort of thing, yet others might. Even if you find someone who got a perfect score and didn't follow these rules, your exam may be graded by someone who is just a little bit less generous.

It seems pretty easy to put a short, simple c-style comment at the beginning of each file, and maybe to use two blank lines rather than one in a few places in your source file. I can't see a good reason not to do this, under the circumstances.
 
Brunno Silva
Greenhorn
Posts: 8
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I am not starting any file with this comment. As you sad, you should not you must. I am using these comments as implementation comments, and only when necessary.


Thanks Marcelo. About the implementation comments, shouldn't it be after the class declaration and before any variable?

Did you look at the part labeled Java Source File Example?


Thanks Jim. Indeed, I was thinking in the Java Source File Example when I wrote the quoted line in your post. After reading your text, I think my approach will be to let 2 blank lines between the package and the beginning comments only (like in the example mentioned). The comments only are going to have class name, version information, date and copyright. My build file will take care of that.

(1) About the Copyright, if the spec relates the company name as "FBS", I'll write "Copyright [yyyy] FBS".
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic