School of Engineering and Applied Science Department of Computer Science CSci 53 -- Introduction to Software Development  http://www.seas.gwu.edu/~csci53/fall05 Prof. Michael B. Feldman  mfeldman@gwu.edu

Style Guidelines

A. Identifier Naming

1. Use identifiers that have meaning in the particular problem. Do not use single letter names such as a or i unless the single letter has problem-specific meaning.
2. Make identifiers easy to read. For example, use currentValue instead of curval.
3. Keep identifiers to a reasonably short length.
4. Use the underscore character to separate words of a constant; avoid underscores in variables.

B. Identifier Case

1. Use UPPERCASE for constants.
2. Use TitleCase for class, package, and interface names.
3. Use lowercase for variable and method names, except for the first letter of each word other than the first word. For example, minTaxRate. Note that all reserved words must be lowercase.

C. Indentation and use of braces ({})

1. Indent the code in any block by two or three spaces. Be consistent! If you prefer two spaces, use two spaces for indentation throughout your code. Note that code from the book uses three space indentation, but Prof. Feldman's uses two.
2. When modifying code from the book or from Prof. Feldman, you must remain consistent to the original coder's style OR you must change all of the original spacing to match your own style.
3. In a switch statement, indent each case label two or three spaces. Indent all code associated with a case two or three additional spaces.
4. Do not use the tab key for indentation; use the space bar instead.
5. Put the left brace ({) starting each new block on a new line. Line up the opening left brace, and the corresponding right brace (}) with the first letter of the associated reserved word (while, if, else, switch, etc.). For example:

while(value < 25)
{
  value += 5;
  System.out.println ("The value is 11 + value);
}
 

6. The book usually omits braces on single-statement blocks, but we require braces on all blocks. This is to make it easier to add a statement to a block, or to remove a statement from one. For example, the book would allow
 


if (x == 1)
  y = 5;
else
  z = 10;

but we require

if (x == 1)
{
 y = 5;
}
else
{
 z = 10;
}

and will grade accordingly. This might seem like a lot of extra work, but it pays off later. To see this, consider adding the statement p = 4; to the block containing y = 5; In the first case, you'd have to remember to add braces; in the second case, the braces are already there, so just add the statement!

7. Put the left brace ({) starting each new block on a new line. Line up the opening left brace, and the corresponding right brace (}) with the first letter of the associated reserved word (while, if, else, switch, etc.). For example:

while (value < 25)
{
  value += 5;
  System.out.println ("The value is 11 + value);
}
 

8. The single exception to the bracketing rule is an if statement(s) that is nested inside an else block. You may, as a personal style choice, write nested if statements in the style of either example A or example B. Notice that example A and example B are logically identical.

 

EXAMPLE A	EXAMPLE B
if (x < 5) {   y = 9; } else {   if (x > 25)   {     y = 100;   }   else   {     y = 0;   } }	if (x < 5) {   y = 9; } else if (x > 25) {   y = 100; } else {   y = 0; }

D. Spacing

1. Carefully use white space to draw attention to appropriate features of a program, but do not put excessive amounts of white space between blocks. Usually one or two lines will make the division clear.
2. Put one space after each comma in a parameter list (a, b, c, d, e).
3. Put one space on either side of a binary operator (x < 7).
4. Do not put spaces immediately after a left parenthesis or before a right parenthesis. Write (noName), not ( noName ).
5. Do not put spaces before a semicolon.
6. Put one space before a left parenthesis, except before an empty parameter list, e.g. Keyboard.readInt();.
7. When declaring arrays, associate the brackets with the element type, as opposed to the array name, so that it applies to all variables on that line. For example:

int[30] listl, list2;
8. When referring to the type of an array, do not put any spaces between the element type and the square brackets.

E. Messages and Prompts

1. Do not condescend.
2. Do not let humor obscure your meaning or insult the user or reader of your code.
3. Be informative, but succinct.
4. Define specific input options in prompts when appropriate.
5. Specify default selections in prompts when appropriate.

F. Output

1. Label all output clearly.
2. Present information to the user in a consistent manner.

Documentation Guidelines

A. The Reader

1. Write all documentation as if the reader is computer literate and basically familiar with the Java language.
2. Assume the reader knows almost nothing about what the program is supposed to do.
3. Remember that a section of code that seems intuitive to you when you write it might not seem so to another reader or to yourself later. Document accordingly.

B. Content

1. Make sure comments are accurate.
2. Keep comments updated as changes are made to the code.
3. Be concise but thorough.

C. Header Blocks

1. Every source code file should contain a header block of documentation providing basic information about the contents and the author.
2. Each class and interface, and each method in a class, should have a small header block that describes its role.
3. Each header block of documentation should have a distinct delimiter on the top and bottom so that the reader can visually scan from one construct to the next easily. Here are two examples; whether you prefer hyphens or asterisks, try to use them consistently. Note that the javadoc documentation tool has its own required comment format; use that if you're preparing a file for javadoc.
   

//---------------------------------------------------
//               Header block
//---------------------------------------------------

//***************************************************
//               Header block
//***************************************************

D. In-Line Comments

1. Use in-line documentation as appropriate to clearly describe interesting processing.
2. Put a comment on the same line with code only if the comment applies to one line of code and can fit conveniently on that1line. Otherwise, put the comment on a separate line above the line or section of code to which it applies.

E. Miscellaneous

1. Avoid the use of the /* */ style of comment; instead use the // style to begin each comment  line.
   
2. Don't wait until a program is finished to insert documentation. As pieces of your system are completed, comment them appropriately.