Coding Guidelines
1. Introduction
For the purposes of this document I want to compare programming with writing a novel. In a novel, you will find characters, locations and settings, and a more or less complicated story which evolves out of the interaction of characters, locations and other events. A computer program is pretty much made of the same ingredients. You will find variables and objects which go through certain changes, just like the characters in a novel; you will have settings and locations which constitute the environment of the piece of software, and events which may originate from user interaction or the surrounding system components. The story in the novel might be liked to the algorithms and rules coded in the program.
As many different kinds of novels are there, as many are computer programs. So on the level of content we don't find many similarities between all the kinds, and consequently cannot derive rules which hold true for each and every type of computer program. However, on the level of orthography, syntax and punctuation we'll find that, at least in novels, a standard has been set which is followed in most modern works of literature.
Syntax and orthography depend on the natural or computer language used in writing a novel or program and are crucial for understanding or error-free compilation. Punctuation depends much less on the language and can be varied in certain ways. It aims at making the text more legible and therefore, more intelligible.
Consider the following sentence:
' I am NOT going to eat
THIS bun !!!" - Harry proclaimed while
the Waiter watched him
wide-eyed .
Though grammatically and semantically correct, this piece of text is hardly legible due to its uncommon punctuation, capitalization, spacing, indenting and line breaks. A novel written entirely in this style would not be much fun in reading.
While there is a standard of rules on formatting and punctuation etc. in modern publishing, I feel that in programming such a standard is still missing. This results in every piece of code looking differently, and consequently programmers have difficulties in understanding others' code. In our time, which its huge output of code that constantly needs re-writing, debugging and development, these difficulties constitute a major problem to efficient code maintenance. Usually companies set up certain rules for their programmers, but sometimes programmers are reluctant to follow these rules. Reasons for this might include:
- the rules are either too complicated or result in too
much additional work,
- the programmers prefer their own established way of typing, or
- the programmers cannot write consistent code due to poor training.
In this document I propose a simple and consistent system of program formatting rules, covering important aspects as legibility, transparence and reusability up to the level of semantics. They are all aimed at increasing the quality of code. As the quality of a programmer, who needs to have a keen eye on details, can be accurately judged by the consistency of his coding, I hope that the programmers reading this can derive some benefit and, by adopting the methods given here, increase the quality of their code and their own expertise.
The rules and examples given here are based on the language Java. However, they can very easily be applied to other languages as well.
2. Syntactic level: Punctuation rules
A punctuation character here means any character which is neither a letter or a digit. The importance of punctuation characters depends on the programming language. For legibility, the most important punctuation characters are whitespace, i.e. space, tab and line break. Proper use of these greatly increases intelligibility of the code. The space character should not be used for indentation, except in special cases where the tab is inappropriate. It should be used for separation purposes only.
Separation
Separation can be dead, omissible, weak, strong or very strong. A dead separation is one which has become obsolete, such as whitespace at the end of a line or lines consisting only of tabs or spaces. It is good style to avoid them though they can be hard to spot.
An omissible separation is a separation that is not neccessary for the correct compilation of a program. Examples:
i = 5;
a = b + c;
for (int y = 0; y < array.length; y++);
The space characters in the above examples are omissible. As they greatly enhance legibility of the code I recommend that you always use them.
A weak separation is a separation which must be there to comply syntactical rules. Examples:
public class Test extends Applet
{ // the space before the bracket is
omissible
int i;
Weak separations can be replaced by tab in most compilers and by line breaks in some. However, this is not recommended, as tabs tend to be formatted differently in different editors and create confusion. Line breaks should only be used when a line becomes very long. In this case, use tabs to indent the broken piece of the line. Examples:
public abstract class LineBreakExample extends java.util.StringTokenizer //
break here!
implements java.lang.Serializable, java.awt.event.MouseListener,
java.awt.event.KeyListener {
The line break should take place before an important
keyword as this is easily overlooked at the end of the line.
Some people go as far as to break lines after each method parameter, e.g.
public Component getTableCellRendererComponent(
JTable table,
Object value,
boolean isSelected,
boolean hasFocus,
int row,
int column) {
This should be avoided as it creates too much white areas around the code. It is a waste of space and doesn't increase legibility. Only use it if there you want to put very strong emphasis on the method. If a list of parameters becomes very long, it is better to indent the broken line up to the position where the parameters start, e.g.
public Component getTableCellRendererComponent(JTable table, Object value,
boolean isSelected,
boolean hasFocus, int row, int column) {
More than one space should not be used for weak separations.
Strong separations are, like weak separations, necessary for correct compilation. Additionally they serve to structure the code. Two line breaks in succession form a strong separation and can be understood as a comment saying "here begins a new section". They are often accompanied by a short comment indicating the purpose of the following section. Example:
public static void main(String[] args) {
// create a class instance and initialize it
Test test = new Test();
test.initialize(args);
You should also use strong separation in the following places:
- between definition blocks of variables that belong
together
- after method and class definitions
- between successive code pieces that have a strong semantic difference, such as
variable and inner class definitions
- after if/else branches and loop statements when the code in the loop is
important.
As a general rule, important and more difficult code should be formatted using generous strong separations and comments. Sections which are self-explanatory and easy to understand do not require a lot of structure.
Very strong separations are strong separations with three and more successive line breaks. They are hardly neccessary and should be avoided in most cases, as they interrupt the smooth flow of the code text. However, for this reason they can be used to create eye-catchers or to put emphasis on certain sections.