Code Complete by Steve McConnell : Chapter 18

The author focuses on coding style and layout. The author first provides an example code written in three different styles and compare them from the point of view of readability. The author also provides examples where the interpretation of a program is different by a human and a computer just because of difference in perception of humans due to layout of the program.

The author points out an observation from Elliot Soloway and Kate Ehrlich that advanced programmers have strong expectations about what the programs look like and their productivity drops drastically when the expectations are violated. The author also enumerates the objectives of a good layout such as accurately and consistently representing the logical structure of the code, improve readability and withstand modifications.

The author compares a program with a book and emphasizes the usage of white-space for following:

• Grouping: White-space should be used to group related statements together.
• Blank Lines: Blank lines should be used to divide a groups of related statements into paragraphs. The author sites a study to highlight that optimal number of blank lines in a program should be about 8 to 16 percent.
  
• Alignment:
• Indentation: The author sites a study to point out that 2 to 4 spaces of indentation is optimal. Anything above 4 spaces or no indentation reduces comprehension.

The author also emphasize the usage of parenthesis to clarify expressions. The author then describes four different layout styles:

• pure blocks
• endline layout
• emulating pure blocks
• begin and end as block boundaries

The author discusses the pros and cons of each layout style and finds endline layout to be very difficult to maintain. The author suggests to either use pure blocks as in Ada or use emulation of pure blocks or begin/end as block boundaries in languages like C/Pascal.

The author then provides some guidelines for layout of control structures. The author suggests to avoid unindented or double-indented begin/end pairs. The author also advises to format single-statement blocks consistently. The author also suggests to avoid gotos.

The author then provides guidelines for layouting of individual statements:

• Length of a statement should be restricted to fit in a single page.
• Use spaces to enhance readability of array references
• Use spaces to enhance readability of arguments
• Align groups of related assignments

The author then provides formatting guidelines for continuation lines:

• Incompleteness of the statement should be made obvious
• While breaking a statement, closely related elements should be kept together
• Routine call continuation lines should be indented the standard amount
• End of continuation line should be easy to find
• Control statement continuation line should be indented by standard amount
• Continuation lines should be indented after the assignment operator
• Each line should have only one statement.
• Avoid statements which have side effects

The author then discusses the trade-off between performance and clarity and correctness of code. The author then provides some guidelines for data declaration:

• Align data declarations
• Use one data declaration per line
• Order declarations sensibly

The author then provides some guidelines on how to layout the comments and routines. The author then provides following guidelines to layout files, modules and programs:

• Put each module in a file
• Separate routines within a file clearly
• Sequence routines alphabetically

The author also provides a standard layout of a source file.