Code Quality

Bart Massey 2013-11-12

Overview

• Misc notes
• Code Formatting
• Code Quality

Misc Notes

• Daily WTF CSOD is http://thedailywtf.com/Comments/Time-Flies.aspx

Code Formatting

• Three main areas:

  • Semantic structuring

  • Syntactic formatting

  • Comments

Semantic Structuring

• Idea: Break code into "chapters" (modules), "sections" (routines), "paragraphs" (blocks of related code), "sentences" (statements)

• Make sure semantic units are clearly delineated

• Comment semantic units at the top if they are unclear

• Pay attention to data declarations: often source of ugliness and confusion

Important Principles

• The Overhead Principle: Time and effort spent on an SE practice should be rewarded by a greater lifetime reduction of time and effort in development and maintenance

  • Many syntactic practices fail the Overhead Principle

• The Invisibility Principle: When changing existing code, changes should be invisibly different from surrounding code

• The Consistency Principle: Whatever syntactic formatting rules are adopted should always be followed in a given codebase

Brace Style: The Real Rules

• Opening brace should be on the next line

  • Exception: the opening brace may be endline (OTBS). Treat it as if it is unindented

• Closing brace should be on its own line after the last line of the block

• Braces should be indented the same amount

• Braces should be indented somewhere between unindented and indented to the block, inclusive

• Brace style must be consistent throughout the program

Expression Formatting: The Real Rules

• Extra parentheses must not be used where anyone with passing familiarity with programming would find them obvious

  • Bad example

    y = ( 3 + ( 2 * b ) )
    

• Whitespace should not be used just inside expr parentheses

• It is acceptable to use whitespace just inside array brackets or function call parentheses, but by no means required (be consistent)

Character Encodings

• Why I advocate TAB-free source files: invisible differences between lines are bad

• Watch out for host line endings: there are three conventions (LF, CRLF, CR) and two are common

• Learn about Unicode (but no Unicode names in programs for another decade or so, please)

Idiomatic Programming

• Always follow the idioms of your language, environment, programming in general

  • Bad example in C:

    for (index = 0; index <= limit - 1; ++index)
    

• Idioms may be syntactic, semantic, or both

  • Stacks in C:

    int stack[5];
    int sp = 0;
    /* push */
    stack[sp++] = 3;
    /* pop */
    result = stack[--sp]
    

Principle Of No Comment

• If it is possible to make a comment unnecessary, do so

Comments By Location

• Top-file comment: Start with copyright notice, then a description of the contents of the file

• Top-data comments: give intent of data structure

• Top-routine comment

  • Nothing for small, simple, "obvious" routines
  • One or two sentences for more complex routines
  • If you need more, consider breaking up the routine

• Top-paragraph comment

  • Extra important, neglected
  • Should provide intent

• Statement comments

  • As needed for intent: should be rare

Why Care About Code Quality?

• The more clear the code, the more it is ready for review

  • Code that is not adequately clear should not be reviewed until that problem is fixed

• The more clear the code, the better you look

  • You will not get hired, raises, promotions if you turn out unclear code; regardless of how "good" it is otherwise

• Clear code should be a vocation, not a religion

  • Save proselytizing for where it matters