CS302/CS367 Style Guide

In This Page: Braces | Whitespace | Indentation | Naming      Related Pages: Commenting | Style Example
Good programming style isn't meant for the compiler, which only requires that you use the correct syntax for the programming language.  Programmers use good programming style to ensure that their source code is easily read and understood by people.  These people typically are members of a program development team and others who maintain or enhance the code.  Good style is particularly important when an author leaves a project.  Then only the source code remains to communicate the author's intentions.

Good style will also help you develop your code more efficiently and minimize bugs.  A programmer's personal style develops over their career.  It is to your advantage to take the time now to establish good programming practices.  Your pesonal style must fit within a number of conventions followed by the industry. In CS302/CS367, we'll concentrate on the following aspects of style: 

Braces
Recommendation: Always use braces even when they are not required.  Selection and looping statements do not require braces if their body contains only one statement. A defensive programming practice is to use braces anyway.  This helps avoid inadvertent errors while developing your code.  However examples we provide and those in the text will often leave out unnecessary braces.

Requirement: Line up braces (i.e. {}). There are several common styles. Pick one style and use it consistently throughout your source files.
 
 Style Example
1
 
statement header {
    body
    body
}
This style is recommended.
2
 
statement header 
{
    body
    body
}
This style is used by our text.

Whitespace
Whitespace is essential for making source files readable.  Meaningful parts of code are grouped together by using the whitespace as a separator.  Whitespace is composed of horizontal whitespace (i.e. space and tab characters) and vertical whitespace (i.e. newline/return character makes blank lines).

Requirement: Use vertical whitespace to organize your source code into meaningful parts.  For example, use blank lines to separate methods from each other, data members from methods, and import statements from comments.  Blank lines are also used to separate groups of statements from eachother to make the major steps of an algorithm distinguishable in a method's body.

Requirement: Use tabs/spaces to indicate the level of nesting (see indentation).

Requirement: Use horizontal whitespace to organize each line of code into meaningful parts.  There are many personal styles of spacing within a line.  It is bad style to not use spaces within a line. For example:
 
good style result = 5 * Math.abs(xCoord - ++yCoord) / (11 % -time)
bad style! result=5*Math.abs(xCoord-++yCoord)/(11%-time)
good style for (day = 11; day < 22 && !done; ++day) {
ok style for (day=11; day<22 && !done; ++day) {
bad style! for(day=11;day<2&&!done;++day){

Indentation
Requirement: Lines must not exceed 80 columns in length including whitespace.  The "standard" screen size is 80 columns. When a line of code exceeds 80 columns, it wraps around to the next line.  This defeats the purpose of properly indenting code due to the confusion introduced by these line wraps. Use a ruler comment in your source files to help you stay within the bounds:
//345678 112345678 212345678 312345678 412345678 512345678 612345678 712345678 8

Requirement: Use tabs/spaces to indicate the level of nesting.  Indentation occurs in fixed-width intervals.  Today most source code editors automatically indent for you typically using an interval of four spaces.  It doesn't matter how much you indent as long as you are consistent throughout your source files.  See the example code, which uses four spaces per indentation.

Level 0: The following items are not indented:

  • File Header Comments
  • import statements
  • Class Header Comments
  • Class Declarations
Level 1: The following items are indented once:
  • Data Member Comments
  • Data Member Declarations
  • Method Header Comments
  • Method Declarations
Level 2+: Other statements are indented at least twice, which is the level of a method's body.  Beyond level 2 you should indent once each time a statement is nested inside the body of another statement (see examples below).  Always indent whether or not the control structure uses braces (see braces).
 
Naming Conventions
Requirement: Follow these naming conventions when choosing names:
  • source files are named the same as their class and ending with the extension .java, the spelling and capitalization must match, e.g. class Example would be in a file named Example.java
  • variable, method and package names begin with a lowercase letter, e.g. age, setAge, width, or computePerimeter
  • Class names begin with an uppercase letter, e.g. class Example, class Dice, or class Person
  • CONSTANTS are in all uppercase letters, e.g. MAX_WIDTH or DEFAULT_COLOR
  • namesWithMultipleWords use initial capitals to make subsequent words distinct, e.g. method setToolTipText, getX, or setColor
    • Requirement: Use descriptive names. The name need not be long, but it must relate to the intended use. Short (i.e. 1 letter) names can be used for temporary variables and loop counters.
    • tableHeight is more descriptive than th. However, height can be used if it is clear that it refers to the height of only one type of object.
    Last Updated: 9/6/2002
    © 1999-2002 Jim Skrentny, CS367 Instructor, skrentny@cs.wisc.edu
    © 2001 Deb Deppeler, CS302 Coordinator, deppeler@cs.wisc.edu