Here is a sample of how this might look:
/*
* Program: sample.java
* Author: John Doe
*
* This is a program which prompts for a person's name
* and writes a friendly message. In a more realistic
* program this paragraph might be quite a bit longer.
*
* Usage: sample
*
* There are no extra words on the command line, since
* sample prompts for the name.
*/
Function comments
Before each function you should have a comment paragraph describing
the function.
The basic idea is that the comments should be sufficient to help
someone determine what the function does and how to call it.
This means that you need to define
function's purpose
special methods (algorithms) used
function parameters: types and purposes
Comments within functions
I expect to see comments within any function longer than about 10 lines
of code.
You should place a comment before blocks of code.
It is not necessary to comment every line.
Descriptive variable names
It is helpful to name variables with names indicating their purpose.
For instance a variable to contain a student's balance in an accounting
application might be named ``balance''.
If there are several balances being manipulated, perhaps the name
would be ``student_balance''.
In general I do not like abbreviations like ``stud_bal'', or
even worse, ``sb''.
I do favor using single character names for index variables for some loops.
This is probably due to writing a lot of Fortran code, but I still find
it acceptable to use ``i'' or ``j'' for loop counters.
Naming variables is very important, but it is not an exact science.
The basic goal is to make your code more readable.
This should help you think more clearly about the code which will help
you write code with fewer mistakes.
The extra time spent typing longer names should pay off in less time
spent confused when the program doesn't work.
Descriptive function names
Similar principles apply to function names.
I would add that you should name functions which are used as procedures
with names beginning with a verb as in ``get_student_balance''.
If a function is used like a ``function'' (you use the returned value),
then the name might be a noun phrase like ``maximum_balance''.
Indentation
Programs are easier to comprehend if indentation matches the code
structures.
Items within the same code structure should be indented the same amount
relative to the beginning and end of the structure.
The beginning and end of the structure should be in the same column.
It is acceptable to indent 3 or more columns per indent level.
However it is simpler to indent one TAB stop (8 columns) since it
only takes one key-stroke to indent with TAB.
Here is a sample piece of code:
/*
* Loop with if/else to illustrate indentation.
*/
for ( i = 0; i < 100; i++ ) {
balance = get_balance ();
if ( balance < 100.00 ) {
/*
* Align comments with the described code.
*/
System.out.println("Getting short of cash");
} else {
System.out.println("Party time!");
}
}
With 8 columns per indent level it is easy to see that the final ``}''
is the closing brace for the for loop.
It is also easy to see the closing braces for the if and else
blocks.
White space
White space can be used to improve the readability of your code.
You can use blank lines and spaces within lines to break things apart
which will assist your brain in observing the structure of your code.
I always use a blank line after the declaration of variables in a function
to separate the declarations from the statements which follow.
I frequently use a blank line after a group of statements to make the
group of statements look connected.
Then I frequently place a comment after the blank line.
Spaces within a line can be used break words apart.
You can see in the previous code segment how I placed a space after
the keyword for and one after the ``(''.
Generally I do not use a space before a comma or semicolon.
Select here to return to the main page for this course.
This page is maintained by Geoffrey Z. Liu,
gliu@wahoo.sjsu.edu. It was last revised on February 1st, 2005.
