A Guide to Coding Style
   Next

A Guide to Coding Style

Justus Piater

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

Abstract

This Style Guide 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:

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

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.

	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

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().

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;

This document evolving from a Java Style Guide by Ed Gellenbeck, Central Washington University, and benefitted significantly from comments by Sébastien Jodogne.

   Next
   2. Commenting Conventions