Code Conventions of Java Programs

Programming in Java consists of writing source code for classes and placing fields and methods inside the class. In the same way that standard and consistent assembly lines make a glass factory productive, standards and consistent code lines make a class factory productive. This guideline makes sense in theory, but carrying it out in practice can be hard because people type whatever and wherever they please . At least in a factory, you have an assembly line that can enforce standards for most activities. With software, enforcing standards has been more difficult. Whether you are an advocate of standard and consistent code conventions or not, your evaluator will appreciate you following one style throughout your code.

Comments and Formatting

You are already familiar with comments, but be aware that the evaluator doesn't want to see too many nor too few. For example, commenting the closing brace is appropriate sometimes. Because Java is object-oriented, a lot of nesting goes on. Losing track of which block you are in is easy, so some gurus place a comment on the closing brace, simply mentioning the loop, method, or class the brace is completing. In small pieces of code, often this practice is not necessary, but in larger ones, it is helpful. You might consider the following a guide for whether to comment a closing brace: If there are more than 100 lines of code between braces or several block-defining brace pairs inside the outer pair, comment the outermost closing brace . When a Java program runs, it couldn't care less about style. However, often the evaluator is pressed for time because he has to pump out his own code, which places the task of grading your project at a low priority (Sun, of course, will deny this ever happens). Therefore, make grading as easy as possible for your overworked evaluator.

The better Integrated Development Environments (IDEs) support a rich set of code style preferences, such as different code layout options, naming conventions for classes, local variables , parameters, and so forth. Often they have a code formatter that reformats a file or a selected block of code according to your formatting settings. They can do even more by optimizing your code onscreen or during import by sorting things, removing unnecessary imports, and more. Be careful about the difference between the nicely formatted code you see in the IDE and what you get in a plain text editor (such as vi). For example, a typical misalignment happens when using the tab character, which might mean a different number of whitespaces, depending on the editor. Please, consider using spaces instead of the tab character because editors interpret tabs in various ways; for example, some convert a tab to four spaces, and others use eight spaces.

The simple practice of indenting brace locations has a major effect on the appearance of your code. Be consistent and use between four and eight spaces for each indent level, like so:

 if() {     System.out.print("indented 4 spaces"); } 

Avoid having all lines flush left, like this:

 if(){ System.out.print("indented 4 spaces"); } 

The Javadoc style recommended by Sun can be seen by using the reference at the end of this Appendix. These comments have a significant impact on your score. Although the individual component score for comments is small, the impression they make on the assessor is more important and will affect score overall. The following is an example method with a Javadoc comment:

 /**  * Returns a String object that is the customer's first name.  * The ID argument must be an integer.  * <p>  * This method always returns immediately, whether or not the  * customer exists.  *  * @param  ID   an integer giving the customer a unique identifier  * @return      the first name of the specified customer  */  public String getFirstName(int ID)  {     //method code  }