Two Wrongs

Code Review Checklist, Second Edition

Code Review Checklist, Second Edition

The second edition is a complete revision and replaces the previous version of this article.

The primary differences are that the second edition

Since I refer to this so often in the course of doing my work, I’ll just dump it here. This is collected from various sources, but primarily ieee standards. I want to use checklists more often – they are really cheap to make and scientifically proven to prevent mistakes. Anyone not using checklists more are doing themselves a disservice.

Checklist

You’ll have to excuse the sorry formatting of this – I haven’t yet figured out a good way to do the right thing with html and css though I’m sure it’s possible.

Maintainability

  • Review request……….IS FOR SMALL, ATOMIC CHANGE
  • Description………….CONTAINS SPEC./REQUIREMENTS
  • Names and concepts………….HAVE OBVIOUS MEANING
  • Non-obvious mechanics…………….ARE DOCUMENTED

Correctness

  • Code in revision………………………..BUILDS
  • All non-obvious logic…………..COVERED BY TESTS
  • Unit tests…………………TEST MANY EDGE CASES
  • Test plan………………….PRESENT AND EXECUTED
  • Race conditions……………………CANNOT OCCUR

Invalid Inputs/State

  • Input box……………..HANDLES ARBITRARY STRINGS
  • Numbers………………………..CAN BE NEGATIVE
  • Integers………………………….CAN OVERFLOW
  • Floating-point values…..HAVE SUFFICIENT PRECISION
  • Strings………………..ARE ESCAPED IF NECESSARY
  • String operations…………..USE EXPLICIT CULTURE
  • Dates………………………WORK PAST YEAR 2038
  • Network loss………………………..IS HANDLED

Usability

  • Error messages………….STATE PROBLEM SUCCINCTLY
  • User-facing errors……………..SUGGEST SOLUTION
  • Timestamps…………………….INCLUDE TIMEZONE
  • Pers. ident. information…………..NOT PERSISTED

First Edition (Published )

This version was a bit of throwing items at the wall to see what sticks. It didn’t turn out to be very usable for me. I’m keeping it here anyway, in case someone else is interested.

Correctness

  • Is the code correct?
    • Meeting performance requirements?
    • Compliant with standards?
    • Compliant with relevant laws?
    • Logic satisfies requirements?
    • Appropriate coding methods?
  • Is the code consistent?
    • Internal consistency between components?
  • Is the code complete?
    • Enough functional diversity?
    • Sufficient fault detection?
    • Maintenance made easy?
    • Proper algorithms chosen?
    • State/mode definitions sensible?
    • Input/output validated?
    • Exceptions handled well?
    • Faults get reported/logged?
    • Transactions monitored?
    • Critical configuration data in place?

Edge-cases

  • Is the code accurate?
    • External interfaces to spec?
    • Correct data formats chosen?
    • Sufficient precision in floating point values?
    • No loss of precision in intermediary computations?
    • Well-defined integer overflows?
    • Models validated against real effects?
  • Is the code testable?
    • Each element testable to objective acceptance criteria?

Comprehension

  • Is the code documented?
    • Understandably?
    • Unambiguously?
    • Specifying all components?
    • Defining all mnemonics, abbreviations, and symbols?
  • Is the interface good?
    • Correct and complete?
    • Responding fast enough?
    • Presenting sufficient information?
    • Reporting errors understandably?