Introduction to Elements of Layout Style #1

Saturday November 19th, 2011

Last month I wrote a blogpost about the importance of white space in program source code. During my day to day work I've experienced that good consistent layout of source code can help and improve the understanding and maintainability of the program code. For new software developers it even help to avoid pitfals caused by bad layout practices.

I make a clear distinction between layout style and program style. Layout style is such things as proper use of white space, indentation, placement of brackets and parenthesis, file header comments, file footer comments, class comment headers, etc. Where the layout style ease the way you read the program, the programming style extends this with also giving best practices that affects the program and helps you to avoid pitfals - usually by avoiding certain syntactic constructs that may give cause to uncertainties. The source code must be easy to read and understand. Otherwise it is difficult to maintain. And 80% of all programming is maintenance programming - fixing bugs in or extending existing code. ^[1]

Maintenance programmers spend 50 to 60 percent of their time trying to understand the code they have to maintain, and they appreciate the time you put into documenting it. Parikh and Zvegintzov 1983

With this blogpost I intend to start a series of blogposts about the elements of layout style. I will take offset in C++ as this is my preferred language but naturally some of the best practices may be relevant in other  programming languages as well. If I can I will attempt to back up the suggested practices by quoting facts from evidence findings as documented in papers, so that the recommendations are as objective as possible. If evidence can show why one layout style should be prefered over another, then I will back that up, rather than use my own gut and subjective feelings. I already know that it is difficult to find objective studies as very little has been done in this area. Some stuff may come from studies made in other fields than software development.

Topics

Below is a list of some of the topics that I intend to bring up - not necessarily in that order:

• The consistency principle
• The boy scout principle
• File sections - the header section, include section, classes sections and footer section
• The class and function headers
• Maximum number of lines in each file and maximum number of characters on each line
• White space - initially covered in the blogpost White space matters in program source code (October 2011).
• Indentation, tabs and space
• Placement of statement sections - and where to put the curly brackets
• Vertical alignment
• Source code documentation
• Beautifiers and pretty printers
• Enforcing coding layout style

Inspiration

To start the series I have found this relative new video from the Programming Style and Your Brain keynote talk from Yahoo User Interface Conference (YUIConf) 2011 with Douglas Crockford - author of the JSLint tool for Javascript - presenting javascript programming practices. Even though it is about Javascript programming language some of the same issues are relevant in C++ as well. Notice that you as C++ programmer should be large enough to laugh about his stabs at C++. Also you should note that most of the issues in this video is about program style - not layout style.

Updates

• Your Brain Cares About Code Style, The Code Dump blogpost December 10th, 2011 by Aviv Ben-Yosef (see also reddit comments).

More

• C++ CheckStyle - The hunt for a good code layout checker (January 2010)