Java Reference
In-Depth Information
Caution Try to avoid using automatic code reformatters for this assignment. Occasionally they will refor-
mat your code in a manner allowed by the coding conventions but contrary to the way you (or the assessor)
would want to see it. Unfortunately, once this has been done, it is hard to undo, and most automatic format-
ting tools do not provide an easy way to review the changes before accepting or denying them.
Variable Declaration Formatting
Variables should be declared one per line, preferably with comments following the declaration
where applicable.
The Sun Coding Conventions state that you may separate variable names from their types
by either a space or by tabs. Unfortunately, using multiple tabs can result in you spending too
much time reformatting code when you add a new variable later, so we recommend you
always conform to a single space between the type and the name of the variable.
Where possible, variables should be initialized when they are first declared. Furthermore,
variables should be declared near the start of the smallest enclosing brace that provides the
necessary scope. You should not wait to declare a variable until just before you use it.
Formatting of Comments Within the Code
Two forms of comments are allowed within Java source code: documentation comments
( Javadoc comments) and implementation comments (all other comments).
Javadoc comments will be covered in more detail in the section on Javadoc later in this
chapter; for now, suffice it to say that Javadoc comments are designed to create API documen-
tation that another programmer can use to learn how to use your class and its associated
constants, methods, (and possibly) variables without looking at your source code. Since
Javadoc comments are designed to be used by external programmers, they should explain
conceptually how your code works as a whole—they should never get into implementation
details.
Implementation comments, on the other hand, are supposed to give hints to program-
mers (or the assessors) who are looking at your code as to what is happening.
Caution Do not go overboard with adding implementation comments to your code. If you are using
good names for your classes, methods, and variables, your code will be generally self-documenting. In such
cases, adding too many comments is self-defeating—the comments distract from the code and quickly fall
out of date.
Implementation comments come in two flavors: the block comment (enclosed between
/* and */ tags), and comments that start with the tag // and continue until the end of the line.
When adding a single comment line, or adding a comment to the end of a line of code, we
recommend that you use the // comment delimiter, as shown in the following examples:
// this is an example of a comment using a single line of text
doSomething(); // this is an example of a comment at the end of a line
Search WWH ::




Custom Search