Notes About Programming Style

By: David R. Tribble
Version: 1.00, 1998-04-16

CONTENTS

  1. Introduction
  2. Comments
    1. Comment Lexicon
    2. Comment Grammar
    3. File Comments
    4. Function Comments
  3. Indentation and Whitespace
    1. Indenting
  4. Tabs, Spaces, and Newlines
    1. Alignment

INTRODUCTION

This treatise does not, in any way, attempt to resolve or dispute the religious wars concerning "good", "bad", or "ugly" programming style. What it does do is describe the particular programming style used in the set of source code created by the author. As such, it is intended to be used as guide for other authors, especially those who want to add to or otherwise enhance the original source code.

COMMENTS

Comments are the most important thing about source code. True, a good architecture and a sound object model are the raison d´être for a set of programs, but comments are the soul of the implementation as embodied in the source code itself. Shoddy, insufficient, or excessive commenting clouds the soul of a program, no matter how well it functions.

C.1 Comment Lexicon

Source code uses the "//" style of comments rather than the "/**/" style. This is a little bit easier to read and makes the source lines a tad bit shorter.

Example:

// This is a comment

A few exceptions are allowed for this rule. In particular, short comments embedded in the middle of source lines require the use of the "/**/" style of comments.

Example:

extern int bar(int a, int /*unused*/);

C.2 Comment Grammar

Comments are complete sentences, and begin with capitalized words. Exceptions to these rules are allowed, such as eliminating redundant "noise" words like "the". The case of variable and functions names is never altered in comments even if they occur as the first word of a sentence (since C++ is a case-sensitive language). Such names should usually appear within single quotes (e.g., 'count'), especially if their appearance would otherwise make the sentence confusing.

Example:

// Initialize members // 'count' is incremented here

Variable, function, constant, and type names are quoted within comments (so that they are not confused with regular words).

Example:

// Adjust 'owner' object // Increment counter 'counter'

C.3 File Comments

Every file begins with a block comment containing the following items:

  • File name.

  • Purpose for the file.

  • Revision (edit) history. Each revision entry contains:
  • Revision number. Minor numbers should contain leading zeroes, so that there is no confusion or the ordering of revision numbers such as 3.1, 3.10, and 3.2. This also facilitates more effective lexicographical sorting.
  • Date. Dates should be specified in ISO-8601 format: YYYY-MM-DD.
  • Author. Initials alone may not be sufficient, especially if the source is modified by many people across widespread locales.
  • Description of changes made.

  • Copyright notice. The dates should cover the years of the first and last revisions made to the file.

    • The last line of the file is a simple comment containing the name of the file. (This is useful when perusing printouts since it serves as a visual indicator of the end of the file.)

    Example:

    //===================================================================== // dir/foo.h « File name // Class definitions for foos and bars. « Description // // History « Revision history // 1.00, 1998-04-01, Ima Nauthor. // First cut. // // 1.01, 2000-01-02, Yura Nuther. // Fixed Y2K bugs. // // Copyright ©1998-2000, by Ima Nauthor, all rights reserved. « Copyright notice //--------------------------------------------------------------------- file contents go here // End dir/foo.h

    C.4 Function Comments

    Every function definition is preceded by a block comment containing the following items:

  • Function name, which includes the class prefix.
  • Description (purpose) of the function.
  • The function arguments should be mentioned in the description, so that their purpose is clear.
  • Return values, if any.

    • Example:

    //--------------------------------------------------------------------- // Foobar::twiddle() « Function name // Twiddle the foobar with index number 'i'. « Description // // Returns « Return values // True if successful, otherwise false. //--------------------------------------------------------------------- bool Foobar::twiddle(int i) { function code goes here }

    INDENTATION

    I.1 Indenting

    Statements are indented using spaces (not tabs). Each level of indentation is exactly four spaces.

    Example (spaces are shown by the "°" symbol):

    °°°°if (expr) °°°°°°°°foo(); °°°°else °°°°°°°°bar();

    TABS, SPACES, AND NEWLINES

    T.1 Alignment

    Tabs are used only to align source text. Tabs are never used for indentation.

    Example (tabs are shown by the "" symbol, and spaces are shown by the "°" symbol):

    °°°°foo(); ¶// Operation °°°°if (expr) ¶// Test for overflow °°°°°°°°bar(); ¶// Correct overflow

    T.2 Newlines

    Blank lines are used to separate groups of statements.

    Example (empty lines are shown by the "" symbol):

    int Hoggle::complains() { statement; statement;statement; statement;statement; statement; }

    Double newlines are used to separate declaration groups and function definitions.

    Example (empty lines are shown by the "" symbol):

    //--------------------------------------------------------------------- // Foo::one() //--------------------------------------------------------------------- ¶ int Foo::one(int a) { function code goes here } ¶ ¶ //--------------------------------------------------------------------- // Foo:two() //--------------------------------------------------------------------- ¶ void Foo::two() const { function code goes here } ¶ ¶

    Copyright ©1998, by David R. Tribble, all rights reserved.
    The views expressed herein represent only those of the author and no one else.