1. Introduction

This document describes a style guide for writing Java source code. It has been a work in progress for several years and will hopefully continue to evolve in the future. The style guide has been used in many real-world projects during these years and has continually been refined as a result of being used by different programming teams.

The style guide was originally developed for C and C++, and was adapted for Java when that language appeared on the scene. This means that the style guide can be used as a base for style guides for other programming languages than Java, both object-oriented and procedural.

In this introductory section we discuss what a source code style guide is and why it should be used at all, and can be applied to any programming language. Finally, the philosophy that is the foundation of this particluar style guide is explained.

1.1 What is a code style guide?

A code style guide is a set of rules and recommendations for how to write source code. It is often targeted at a specific programming language, but usually contains some sections that are applicable to a number of languages.

Exactly which aspects of code style that are defined in the style guide varies, as does the level of ambition. Some style guides are very specific about details in the code whereas others contain more general rules.

The most common topic in a code style guide is naming conventions. Very often, the rules specify how to name different identifiers in the code, and sometimes there are rules for how to name source code files. Standards for documentation and comments are also frequent topics in a style guide.

A code style guide can also specify rules for the layout of the source code, e.g. in which order constants, methods and variables should appear. The style guide may also specify in detail how a block of code should be indented, how many statements that may be grouped together, and how many empty lines that should separate two groups of statements. It may even regulate where to put the curly braces or if there should be a space or not after a left parenthesis.

A code style guide normally does not talk about such things as good coding practice or principles of object-oriented design. Although important issues, such topics are generally considered to be beyond the scope of a code style guide and should be discussed elsewhere.

1.2 Why use a code style guide?

There are several reasons for using a source code style guide. One of the most important is that it makes the code easy to read and understand and thereby easy to maintain and extend, regardless of who wrote it.

If every programmer in a project uses the same coding style it will be easier to quickly understand code written by someone else than if everybody uses a style of their own choice. Whether you are adding functionality, fixing bugs or refactoring code, the style in use is already correct and you can focus on the real job. There's no need to change your own style temporarily to fit what's being used.

It will also be easier to return to code that you have written yourself but haven't worked on for while if you always write code in a consistent style.

Another important reason to use a source code style guide is that it will specify how the documentation and comments should be written. Again, this is to make the code easier to understand and maintain. It also helps to make the documentation happen, and not just be that item in the project plan that never is finished.

By using a code style guide, the number of arbitrary choices that has to be made by the programmer is reduced. If there are rules for naming and documentation, the programmer doesn't have to spend time thinking about those things, and can devote all energy towards creating and implementing the algorithms.

A code style guide also makes it easier to conduct code reviews, which is a software engineering practice with documented benefits. This also works the other way around, code reviews can help enforce a consistent style.

Regardless of all good intentions, it must be remembered that a code style guide is a tool that supports the coding. It has no merits of its own, and should never be a set of strict rules that must be obeyed at all times. Even more important is that a code style guide must be agreed upon by all programmers in the team, otherwise it is of little use.

Finally, the most important thing is that you actually use a code style guide, not which style guide you use. Local adaption of one or more style guides may be the best choice for your particular needs. If that is the case, document your adaption. It doesn't have to be more complicated that saying "We'll use that Franzen guy's naming convention, but his file layout ideas really suck, let's use the Netscape layout rules instead".

1.3 The philosophy of this style guide

The code style guide described in this document concentrates on the following topics:

• Naming and organisation of source code files
• Identifier naming
• Class layout
• Source code documentation

The guiding principles for this code style guide is to specify only things that help to make the code more easy to read and understand, and thus more easy to maintain and extend. This is consistent with what we have said is the most important aspect of a code style guide.

You will not find any detailed rules about code layout in this style guide. There are no rules for how many positions a code block should be indented, if there should be a space before or after a parenthesis, or if the left curly brace following an if statements should be placed on the same line as the condition or on a line of its own.

What you will find is a number of rules and recommendations that empirically have been found to help in making source code easy to read and understand. We have also tried to motivate why a rule is in the style guide and to give examples on how the rules make the code better.

We recognise that a source code style guide can never be complete or contain recommendations for all possible situations that may arise when writing code. We also recognise that a style guide isn't always applicable, and that there are situations when its rules must be broken. As long as a deviation from the style guide can be motivated and documented, it is perfectly acceptable. If some rules are broken regularly, it may indicate that they don't fill a purpose and should be revised. Remember that the style guide is there to support the programmer, not the other way around.