Coding Style Guide

From jmips

Authors: fse0000, fse0070, fse1337, ptb

Overview

This page explains the jMIPS house coding style which should be followed when contributing to the code.

The most important aspect of coding style is its role in making sure code is easily maintainable and a big part of this is making sure the code is easily readable. Below are some general guidelines for making your code easy to read:

• Be consistent. Try to follow the style of the surrounding code (or change the surrounding code if its style is unreadable).
• Don't optimise your code so much that it isn't easily understandable. It is more important that the code be maintainable than it be fast or space efficient. Try and keep your declarations together at the top of the method, for example, and never mind about minimising their local scope or duration. People see things more easily if they're where they're expected to be!

If in doubt, follow the Java Code Conventions!

Comments

• Do not comment to excess. If the code needs commenting, it is wrong.

• All methods and classes must be block-commented.

• Block comments should be in grammatically correct full sentences, each starting with a capital letter and ending with a full stop. The block comment starts on the method or class indent column (methods will be indented with respect to their class and so will their block comment).

• Inline comments do not start with a capital and do not end with a full stop, and do not form full sentences (usually).

• Start inline comments on the same column (notionally column 40, but it is allowed to vary if it's too hard to do that locally), and never carry them over to another line. Maintenance tends to move and separate lines, and the comments get separated too!

Appearance and Readability

• Write code that can be presented on an 80-column screen, so all lines stop on column 79.

• Use plenty of whitespace. For example:

public exampleMethod() {

    String example;
}

Note that after the method declaration we leave a space followed by the brace on the same line. We then leave a new line before we start writing the body of the method. Finally, close the braces vertically underneath the start of the method declaration. Lining things up is important!

• After declaring a method or a class, there should be a line underneath which is kept blank for clarity. Methods in a class are separated by one empty line.

• A single space should appear before and after operators and relations.

• A single space should be left before and after parentheses ( ) are used in expressions and certainly in if or switch statements, etc, although function and method calls may cuddle-up close to the parentheses if that's done locally.

• Where possible, line up variables, equals signs, etc. It makes it easier to digest.

• When introducing an opening brace {, it should be positioned at the end of the line after a single space. The corresponding closing brace } should be in line with the opening of that block.

• Use 4 spaces of indent inside blocks. The only exception is a switch, where the case label itself can be indented by only 2 spaces, not 4, in order to make itself more obvious. Consistent spacing is essential for legibility.

• Do conditionals like this (else 'cuddles' up to braces, four space indent, space around parentheses):

if (foo) {
    ...
} else {
    ...
}

• Do try/catch like if/else:

try (foo) {
    ...
} catch(bar) {
    ...
}

General Coding Practice

• Do not use long names for variables, but if you call a variable "x", at least leave an inline comment at the declaration site reminding the reader what it stands for here. Such comments should all be aligned if applied to more than one declaration in a block of declarations.

• Try not to nest anything and use break whenever possible to get out of a loop early. Treat the exceptional case (short and leads straight to the exit) before the normal case. Never use "else" in a conditional, even when tortured. All this in the name of clarity.

• Method names begin with a lower-case letter, and may have underscores separating distinct words:

     lowercase_with_underscores

or else may use capitals to separate words

      lowercaseWithCapitals

Exceptionally, some static methods may be in all-caps, to indicate to the reader that they are really only there because Java does not have proper macros, so we have to write these instead.

• Class names should begin with a capital, with the rest of the word continued in lower-case.

     EachNewWordStartsWithACapital

Exceptionally, if the name is an acronym, we may write the whole class name in capitals.

• We initialise arrays with { 1, 2, 3, } when we do initialise them. That is, we leave a trailing comma, and spaces between initialisers. We prefer to spread the initialisation over several lines with one element per line only if there's something complicated going on, or there's a fairly long list of entries.

• Functions/methods should be named either after what they do or what they produce, and often may carry a suffix indicating the type of their operands/result as a reminder, e.g. write32, read16. Variants which do things in a variant way should carry the variation as a suffix in their name, e.g. write vs writeSync.

Summary

Briefly, the most important points are:

• Try to follow the style of the surrounding code.

• Write block comments in full sentences and use proper spelling and grammar.

• Inline comments should be aligned with each other.

• Write code that can be presented on an 80-column screen, so all lines stop on column 79.

• Use plenty of whitespace.

• Where possible, line up variables, equals signs, etc. Lining things up is important!

• No tabs! Use four spaces instead.

• Try not to nest anything, never use "else" in a conditional.

• Use sensible names for methods, variables, etc.