Code Quality

Bart Massey 2013-11-12


  • Misc notes
  • Code Formatting
  • Code Quality

Misc Notes

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
Last modified: Tuesday, 12 November 2013, 10:04 AM