Layout of source code


The most obvious and perhaps contentious issue of code presentation concerns brace positioning. Brace is a common name for the curly bracket.

The compiler may completely ignore the code presentation format but that does not mean it is not important. Presentation can illuminate and support your code's structure and help the reader understand what is going on. It can also do the opposite and make it more difficult for the reader. It can also hide bugs.

The three audiences for source code are ourselves, the compiler, and others. The most important audience to consider is others.

The indentation strategy should be consistent across the project. Individual presentation rules such as positioning of braces and number of spaces of indent should always be the same.

Use an indentation strategy that is conventional and can be described concisely.

K&R style of brace positioning was established in The C Programming Language and may be the dominant style for Java code.

int k_and_r() {
    int a = 0;
    return a;
}

Pick a good coding style and stick to it. Unless your team already has a coding standard, in which case use it. There are advantages to the company adopting the same style--less noise in version control where one person is changing the style, less time spent understanding the layout when making a change, etc.

Summary

Presentation is one of the things that differentiates good code from bad code. It is an important skill to lay out code for maximum clarity within the guidelines of the company coding style being followed. It is a reasonable thing to assume that carefully laid out code has been carefully designed. It is even more reasonable to assume that sloppily laid out code was not carefully designed.

Good programmers avoid pointless arguments, are sensitive to others' opinions, and are humble enough to know they are not always right. They understand that code layout can impact readability and try to make the code as clear as possible. They adopt the house style even if it contradicts their preferences, for the greater good.

Bad programmers are closed-minded and argue over the most trivial things. They have no consistent personal coding style and trample over others' code in their own style.

Article notes

According to Code Craft, what is the most obvious, and contentious, issue of code presentation?
What is a common name for the curly bracket?
Is the format of code not important since the compiler completely ignores it?
What are the three audiences for source code?
Who is the most important audience for the source code, according to Code Craft?
What is the Code Craft recommendation for what indentation strategy to use?
What is the name for the style of brace positioning that was established in The C Programming Language and may be the dominant style for Java code?
What is a reasonable thing to assume about sloppily laid out code?
Previous Next