Coding Design & Style Guide

For coding assignments in this course, your program will be evaluated not simply on correctness (i.e., whether it follows the assignment specification), but also on good design and coding style. This document details specific design and style issues that I will look for when reviewing your programs. As many aspects of design are highly situational, this is by no means an exhaustive list, but you should strive to follow these guidelines as well as exercising your own judgment when designing your code.

This guide is targeted towards Java code, but most of these principles apply to working in any programming language.

Documentation

Good code should be largely self-documenting - i.e., the code itself (such as variable and method names) should generally make it clear what you are doing. In particular, more documentation is not necessarily better, and it is better to have clear code that doesn't need any documentation versus unclear code with extensive documentation.

Comments should not describe what the code does, but why. Novice coders (or those just starting in a new programming language) often make the mistake of documenting what the code is doing (e.g., "calls the indexOf method"). Such comments are not necessary; as a general rule of thumb, you should assume that the reader is already comfortable with the language. Instead, your comments should provide detail that is not already evident from the code itself.

There are several parts of your code that do generally deserve comments:

• Class headers: Every class should be prefaced with a Javadoc comment summarizing the purpose of the class.
• Method headers: Every method should be prefaced with a Javadoc comment summarizing the purpose of the method, the method parameters, and the method return value. Other information that is often appropriate includes error conditions, any assumptions made by the method, and any changes made to other parts of the program (e.g., modifying an external data structure) that are not evident from the rest of the description.
• Long code blocks: Lengthy blocks of code within a method can often benefit from an inline comment summarizing the purpose of the code block. However, most methods should not be excessively long (e.g., ~20 lines or less), which should minimize the need for inline documentation.
• 'Clever' code: Be careful of writing 'clever' or 'tricky' code. In most cases it is better to rewrite such code in a straightforward way, even if it is marginally less efficient as a result. However, if there's no clear way to make a bit of code self-evident, then a comment should be added to explain.

Whitespace

Proper use of whitespace is essential to the readability of your code. In particular:

• Every new block of code (class, method, conditional, loop, etc) should be indented one additional "level". Languages like Python force you to do this -- languages like Java do not, but you should act like they do.
• The size of each level should be consistent. For example, you are likely to run into trouble if you use tabs to indent in some parts of the program while using regular spaces to indent in other parts. You can use whichever convention you prefer, but you must be consistent. Pay particular attention to tabs and spaces if working in a group - you do not want to be using separate whitespace conventions. Most editors can be configured to insert spaces instead of actual tab characters (this is my own preference, as spaces will always display consistently across editors). If you are using BlueJ, the default behavior is to insert spaces whenever tab is pressed.
• Blank lines should be judiciously used to separate blocks of code. Methods should always be separated by blank lines, as should larger blocks of code within methods.

Line Length

One way to make your code hard to read is to write excessively long lines of code. Many large software companies impose a code width limit of 80 or 100 characters in the interest of readability. For this course, you should not have any lines of code longer than 100 characters (indentation and comments included). To give you an idea of what 100 characters looks like, the following line is 94 characters long:

public double someMethodDefinition(String aStringParam, int anIntParam, double aDoubleParam) {

Many editors have features to graphically indicate where the line width limit is, allowing you to easily avoid exceeding it. Unfortunately, BlueJ does not have this feature. As such, we will not expect you to rigidly adhere to the 100-character guideline, but you should still use reasonable judgment and avoid writing very long lines.

Note that one way to break up a long line in a readable way is to split the long line, then double-indent the line continuation. Below is an example of this:

public double someMethodDefinition(String aStringParam, int anIntParam, double aDoubleParam,
      boolean aBooleanParam, char aCharParam) {
  // code goes here -- note double indentation above
  // this comment is single-indented
}

However, you should think carefully whenever you find yourself writing a long line, even if it's split across multiple actual lines. For example, the above method could perhaps be written using fewer parameters, which would make it more readable and easier to work with.

Naming

Variable names should clearly describe what the variable contains. Local variables with obvious purposes (such as a loop counter) may be named with a single letter (e.g., i); other variables should not. Generic variable names (e.g., foo, var, asdf) should never be used. Variable names should be descriptive but concise; e.g., a name like sumOfAllArrayValues could probably be better named simply arraySum. Variable names should generally be nouns (e.g., arraySum) while method names should generally be verbs (e.g., calcArraySum).

In Java, variable names with multiple words should be formatted using camelCase, e.g., arraySum instead of array_sum. The only use of underscores to separate words should be in constants, which should also be named in all caps, e.g., DAYS_IN_YEAR. Class names should always be capitalized (e.g., String instead of string), while all method and variable names (except for constants) should start with a lowercase letter.

Magic Numbers

"Magic numbers" are numbers in your code that have a meaning beyond their own values. For example, in the line numDays = numYears * 365;, the number 365 has a significance beyond simply being the number 365 -- it's the number of days in a year. Magic numbers like these should be named using constants at the top of the class, as follows:

private static final int DAYS_IN_YEAR = 365; // before all method definitions
...
numDays = numYears * DAYS_IN_YEAR; // in some method

Magic values should never be used directly in your code. Note, however, that not every number actually has a meaning beyond its own value -- e.g., the values 0 and 1 usually do not need to be named.

Consistency and Teams

One of the most important aspects of coding style is consistency -- not only in the areas covered by this guide, but in other areas as well (e.g., whether curly braces go on the same line as their associated keyword or on the next line). You are allowed to make your own style choices in such cases, but you should always be consistent. Unexpected style changes in a program substantially detract from readability even if the individual style choices in question are reasonable.

The issue of consistency is particularly important when working in a team. Since your team members may have their own personal preferences and conventions (which may differ from yours), it is critical to agree in advance which conventions you will use. A great way to waste time and annoy your partners at the same time is to write code using multiple different conventions, then go back later and change all your partners' code to match your own code's style. Avoid this problem and decide on your style conventions in advance!

Modularity

To the extent possible, you should strive to make your code modular. Writing appropriately modular code includes the following:

• Follow the DRY principle ("Don't Repeat Yourself"). You should not have identical or nearly identical chunks of code in your program - instead, move these blocks of code into separate methods and call those. Use of copy-paste is almost guaranteed to indicate a violation of this principle.
• Instance variables should always be marked private (or protected); never public.
• Methods should be compact and perform well-defined tasks. Long methods, or those for which it is hard to succinctly describe what the method does, should be broken up into multiple smaller methods. While there is no formal rule on what constitutes a "long" method, most methods you write should be no longer than 30 lines of actual code. A method with more than 50 lines of actual code (including main) is almost certainly too long and should be modularized.

Dead Code

"Dead code" is code that is not actually active in your program. Such code might include old debugging statements that you commented out (e.g., extra calls to System.out.println), or an old method you wrote that is not actually called anywhere from within your program. While some dead code is an inevitable product of development, you should remove all dead code in your final program. A submitted program should never contain any dead code.