"Code Quality" Ideals

  • Communicates design

  • Is easy to verify

  • Is modular / refactorable

  • Gives context (e.g. attribution)

A Good Book

Steve McConnell, Code Complete (2nd ed), Microsoft 2004

Breaking Code Down

  • Broken into files: typ > 20 and < 1000 lines per file

  • Uses the language's module system: typ one module per file

  • Code broken into "units" (procedures / functions / methods): typ < 200 lines

  • Short statements, small expressions, minimal nesting

Identification and Attribution

  • File should say

    • who originally wrote it
    • what it is part of
    • what it is

  • Attribution by in-file comments

Naming

  • Matters: pick good names

  • Can be too short, too long

  • No funny linguistic tricks

  • Bracketed naming: open/close, start/end etc

Formatting

  • Pick an idiomatic style and follow it

  • Use formatting tools where possible

  • Consistent ample whitespace

  • typ <80-char linewidth

Repetition

  • "DRY" (Don't Repeat Yourself)

  • Use units, macros

  • Simplify algorithms, rewrite data structures

  • Minimum redundant data rule

Intent

  • Good: Description of "strategy" before fancy code

  • Better: Pseudocode before fancy code

Assertions

  • Instance of the fail-early principle

  • Available in every modern language

    assert x==5 "bad x"

  • Never remove assertions (almost)

  • Assertions can make your program faster (?!)

  • Any time you can reasonably check that things are as you expect with an assertion, add it

    • Crashes are better than wrong answers
    • You won't hit the assertions anyhow..right?

Instrumentation

  • Logging and similar

  • Build monitoring and diagnosis infrastructure up front

Last modified: Monday, 26 October 2020, 12:34 AM