"Programs must be written for people to read, and only incidentally for
    machines to execute."
        --Abelson and Sussman
          (Structure and Interpretation of Computer Programs)

    "When developing code you should always choose readability over
    convenience. Code will be read many, many more times than it is
    written..."
        –-Venkat Subramaniam and Andy Hunt (Practices of an Agile Developer)

    * 80% of the lifetime cost of a piece of software goes to maintenance.
    * Hardly any software is maintained for its whole life by the
      original author.
    * Code conventions improve the readability of the software, allowing
      engineers to understand new code more quickly and thoroughly.
        --Java.sun.com (Code Conventions for the Java Programming Language)

    "Rules are for the obedience of fools and the guidance of wise men."
        --David Ogilvy


--------------------
Indentation and Tabs
--------------------

* Use 4-columns for all indentation levels.

* Use spaces for all indenting; do not use hard tab characters.

* Use a text editor that supports variable tab widths and conversion of tabs
  to spaces (examples have been given for vi and nano).


---------------------------------------
Compound Statements (Blocks) and Braces
---------------------------------------

* Indent enclosed statements one more level than the compound statement.

* The opening brace should be at the end of the line that begins the compound
  statement OR on the next line, indented to the same level as the compound
  statement.
  The closing brace should begin a line and be indented to the beginning of
  the compound statement.
  Choose one of the following and be consistent:

    for (i = 0; i < BUF_SIZE; ++i) {        for (i = 0; i < BUF_SIZE; ++i)
        // one or more statements           {
    }                                           // one or more statements
                                            }

* Use braces around all statements, even single statements, when they are part
  of a control structure, such as if-else, for, or while statements.
    YES                                 *NO*
    ---                                 ----

    for (i = 0; i <MAX; ++i) {          for (i = 0; i <MAX; ++i)
        destination[i] = source[i];         destination[i] = source[i];
    }

* Exception: Null loop statement where all evaluation takes place in control
  statement.
    YES                                 *NO*
    ---                                 ----

    while (getchar() != '\n');          while (getchar() != '\n') {
                                            ;
                                        }


-----------
White Space
-----------
* Separate all binary operators with a single space on each side.

* Preceded or follow  unary operators by their operand.
    YES                                 *NO*
    ---                                 ----

    totalPrice = price + tax;           totalPrice= price+tax;
    ++numItems;                         ++ numItems;
    index--;                            index --;

* Do not use space between function name and opening parenthesis.

* Leave 1 space between C key word (such as for, while) and opening
  parenthesis.

* Do not use space between opening/closing parenthesis and
  arguments/expressions.
    YES                                 *NO*
    ---                                 ----

    area = rectangleArea(l, w);         area = rectangleArea (l, w);
                                        area = rectangleArea( l, w );

    while (index < MAX) {...            while(index < MAX) {...
                                        while ( index < MAX ) {...

* In comma-separated lists do not use a space before the comma and use exactly
  one space following the comma. Similar for for loop expression lists.
    YES                                 *NO*
    ---                                 ----

    area = rectangleArea(l, w);         area = rectangleArea(l,w);
    for (i = 0; i < 5; ++i) {...        for (i = 0;i < 5;++i) {...


------------------
Naming Conventions
------------------

* Use descriptive and meaningful names. Comment variable declarations unless
  the variable name is "self documenting" (which it should be in many, of not
  most cases).

* Use "camel-case" for multi-word names:
    totalScore, maxScore, runningTotal, minLevel

* By convention, using upper-case for the first character is reserved for
  classes in Object Oriented languages; in C reserve upper-case first
  characters for structure names.

* Name length and detail should generally be proportional to its scope.
  "studentId" would be used throughout a program, where "sid" (or even "id")
  might be used in a function or block of only a few lines.

* i, j, k (in that nesting order) are common iterator variables for loop; they
  should be used, and generally do not need to be commented.

* x, y are generally understood to be X-Y coordinate variables, and may be part
  of longer variable names:
    getDistance(x, y), screenX, screenY

* Generally avoid cryptic abbreviations. When using generally common
  abbreviations, be consistent. Think of a reader whose first language is
  not English.
    OK                                  Not so OK
    --                                  ---------
    socialSecurityNumber                ssn (may need comment for non-U.S.
                                             readers)
    initialize                          init (not good, but widely used)
    screen                              scr ("screen", "script", or misspelled
                                             "source")
    count                               cnt ("count" or "container")
    reset                               rs, rst (who knows!)

* Common prefixes are i, len, n, num;
    nStudents, numStudents              // number of students
    lenFileName, lenPathName            // length of file & path name strings
    iRecord, iName, iEmployeeName       // think of 'i' = iterator or index

* Use descriptive (and consistent) verbs for function names:
    getInput(...), setBackgroundColor(...), initializePlayingField(...)

* Use "is" prefix for Boolean values (and functions returning Boolean values):
    isOpen, isFinished, isSet, isBitSet, isArchiveBitSet, isLeapYear, isFirst,
    isFirstEntry

* For consistency, use complement names and prefixes for complement
  operations:
    get/set         add/remove      start/stop      insert/delete
    old/new         begin/end       first/last      up/down
    min/max         next/previous   old/new         open/close
    show/hide       increment/decrement


-----------
Line Length
-----------

* Avoid lines longer than 78 characters excluding the new line. Tools and
  terminals still exist that do not handle longer lines, and some operating
  systems (specifically Windows) use 2-character new line sequences.

* Break expressions that will not fit on a single line, using these general
  guidelines:
    - Break after a comma.
    - Break before an operator (the operator will start the next line).
    - Prefer higher-level breaks to lower-level breaks (break on '*' or '/'
      rather than on '+' or '-').
    - Align the new line with the beginning of the expression at the same
      level on the previous line.
    - If the above quidelines produce hard to read code, or code that is
      pushed against the right margin, simply indent 2 levels (e.g. 8 spaces)
      from the current block.


--------
Printing
--------

* All source file and terminal output documentation must be printed using a
  fixed- width font (some examples: Courier, Courier New, Lucida Console).
  Margins and/or font size must be set such that output from an 80-column
  terminal screen will not wrap.

------------------------------------------------------------------------------
Revised: 2008-07-10T10:18-07:00