A Guide to Coding Style

2005-01-14


Table of Contents

1. Naming Conventions
1.1. Variable Naming Conventions
1.2. Constant Naming Conventions
1.3. Method Naming Conventions
1.4. Type Naming Conventions
2. Commenting Conventions
2.1. File Header Comments
2.2. Single-Line Comments
2.3. Trailing Comments
2.4. Documentation of Classes and Methods
3. Formatting
3.1. Indentation and Braces
3.2. White Space
3.3. Line Length
4. Structuring the Code
4.1. Method Complexity
4.2. Modularity
4.3. Clarity and Robustness of Code

This Style Guide[1] summarizes useful coding standards, conventions, and guidelines for writing correct, high-quality, and maintainable code in C, C++, or Java. They are based on industry standards, although often reduced to a simplified form to teach the concepts yet keep the work load reasonable. By following these principles, you will be better able to produce code that is correct, requires less debugging effort, and is easier for the graders to follow.

In the real world, code conventions are important to programmers for a number of reasons:

  • 80 % of the lifetime cost of a piece of software goes to maintenance. Hardly any software is maintained for its whole life by the original author. Code conventions improve the readability of the software, allowing software engineers to understand new code more quickly and thoroughly.

  • Coding standards allow teams of programmers to more easily understand each others code and help spot errors. Rather than coding from scratch, team members are more likely to sharing and re-use code when the style and commenting conventions among team members are the same.

Some of the recommendations given in this document are generally accepted conventions and should be considered mandatory, while others are merely suggestions that may differ between styles. The ultimate goal is readability, and good is what contributes to it. In any case, there is no readability without consistency of style.

Note

This document uses object-oriented terminology and refers to “functions” as “methods”. For the purpose of this document, a “method” is the same as a “function”.

While the code examples are given in Java, the cited principles apply to all related languages.

1. Naming Conventions

The following general guidelines apply to choosing identifier names in your programs:

  • Use full English descriptions for names. Avoid using abbreviations. For example, use names like firstName, lastName, and middleInitial rather than the shorter versions fName, lName, and mi.

  • Avoid unnecessarily long names. For example, setTheLengthField should be shortened to setLength. If you feel that you cannot clearly express the meaning of a variable within a reasonable variable name (up to about 20 characters), you should think about restructuring your code.

  • Avoid names that are very similar. For example, if you store a list of products in a variable called perishableProducts, it may be better to refer to a particular product as thisPerishableProduct (or thisProduct or product) rather than perishableProduct to avoid confusion.

Why use English names? The programming language keywords are in English, and it is difficult to read multiple languages in parallel. Even more importantly, in the real world barely any software code stays within the realm of a single language, forcing us to use English as the de-facto common denominator.

You should write your code with the aim of making it understandable to others. Others will need to read and understand your code and one of the major keys to understanding is through the use of meaningful identifier names.

By using meaningful names, you go a long way towards writing self-documenting code. That is, code that is understandable on its own without requiring accompanying comments. For example, look at the following code segment and determine for yourself that the variable names salesTax and incomeTax are preferable to tax1 and tax2 because the names are self documenting.

      double tax1; // sales tax rate (example of poor variable name)
      double tax2; // income tax rate (example of poor variable name)

      double salesTaxRate; // no comments required due to
      double incomeTaxRate; // self-documenting variable names
    

1.1. Variable Naming Conventions

Choose meaningful names that describe what the variable is being used for. Avoid generic names like number or temp whenever their purpose is not absolutely clear.

Compose variable names using mixed case letters starting with a lower case letter. For example, use salesOrder rather than SalesOrder or sales_order.

Use plural names for arrays. For example, use testScores instead of testScore.

Exception: for loop counter variables are often named simply i, j, or k, and declared local to the for loop whenever possible.

	for (int i = 0; i < MAX_TEMPERATURE; i++) {
	  boilingPoint = boilingPoint + 1;
	}
      

These conventions are common practice in the Java development community and also the naming convention for variables used by Sun for the Java core packages. Writing code that follows these conventions makes variables easy for others to distinguish from other types. They are also increasingly used in C++ and C code.

1.1.1. Declaring and commenting local variables

  • Do not declare several variables within the same statement (separated by commas), except for trivial cases.

  • If the meaning and use of the variable is not clear, add an endline comment (// …) stating what the variable is used for and why. However, a better solution is to choose a meaningful name to avoid the need for the endline comment.

  • Declare variables immediately before they are used, rather than declaring all variables at the top of the method.

    In pre-ISO-1999 C, declare all variables at the beginning of the innermost block that delimits its intended scope. It can sometimes be a good idea to open a new block specifically for declaring variables close and limited to their local use.

  • Whenever possible, initialize the variable with its starting value in the declaration statement.

    In pre-ISO-1999 C, if the first use is far away from the variable declaration, it is perhaps an indication of poor code design.

1.2. Constant Naming Conventions

  • Use ALL_UPPER_CASE in your constant names, separating words with the underscore character. For example, use TAX_RATE rather than taxRate or TAXRATE.

  • Avoid using literal numbers in the code. Literal numbers like 27 that appear in the code require the reader to figure out what 27 is being used for. Consider using named constants for any number other than 0 and 1.

	day = (3 + numberOfDays) % 7; // NO! uses literal numbers

	static final int WEDNESDAY = 3;
	static final int DAYS_IN_WEEK = 7;

	day = (WEDNESDAY + numberOfDays) % DAYS_IN_WEEK; // Yes, self-documenting
      

1.3. Method Naming Conventions

Try to come up with meaningful method names that succinctly describe the purpose of the method, making your code self-documenting and reducing the need for additional comments.

Compose method names using mixed-case letters, beginning with a lower case letter and starting each subsequent word with an upper case letter.

Begin method names with a strong action verb (for example, deposit). If the verb is not descriptive enough by itself, include a noun (for example, addInterest). Add adjectives if necessary to clarify the noun (for example, convertToAustralianDollars).

Use the prefixes get and set for getter and setter methods. Getter functions merely return the value of a variable; setter functions change the value of a variable. For example, use the method names getBalance and setBalance to access or change the variable balance.

If the method returns a boolean value, use is or has as the prefix for the method name. For example, use isOverdrawn or hasCreditLeft for methods that return true or false values. Avoid the use of the word not in the boolean method name, use the ! operator instead. For example, use !isOverdrawn() instead of isNotOverdrawn().

These conventions are common practice. Writing code that follows these conventions makes methods easy for others to identify. Even though variables and methods both begin with a lower-case letter followed by mixed case, they can easily be differentiated from each other because method names begin with a verb and always are immediately followed with a set of parenthesis, for example: moveAccount().

1.4. Type Naming Conventions

Class names are always written in mixed case like method names, but begin with an upper-case letter.

By analogy, typedefs of structured types should be named in the same way.

In C, structs and enums are typically named in all-lowercase, ending with _t. However, you will usually want to typedef such types.

A case could be made for naming typedefs of non-structured types according to C-style conventions, to distinguish them from structured types. However, I feel it increases readability greatly if all typedef names begin with an upper-case letter, to distinguish them from variable names:

class SomeClass { … };

typedef struct node_t {
  void *content;
  struct node_t *next;
} Node;

typedef enum season_t { SPRING, SUMMER, FALL, WINTER } Season;


[1] This document is evolving from a Java Style Guide by Ed Gellenbeck, Central Washington University, and benefited significantly from comments by Sébastien Jodogne.