CSCI 2101B
Data Structures

Bowdoin College
Fall 2021
Instructor: Sean Barker

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.


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:


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

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.


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!


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

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.