Codebase evaluation checklist

Codebase checklist

Highly opinionated checklist, but each of these items will make it faster (for me) to onboard and contribute to a codebase.

  1. Project self-containment
    1. Backing services are defined in the project and under version control
    2. External dependencies are limited to a runtime and task runner
  2. Test presence and separation
    1. Unit tests can be run without any further setup or configuration tasks
    2. Clear separation of unit and types of non-unit tests
  3. Test runner is idiomatic
    1. Tests can be executed using project task runner
    2. Test results are reported in human and machine readable forms (e.g. HTML and XML)
    3. Test coverage results are reported in human and machine readable forms (e.g. HTML and XML)
  4. Build system is idiomatic
    1. One single command runs the build and generates an artefact
    2. Minimal set of global dependencies required to run the build
  5. Coding style
    1. Coding style is specified local to the project
    2. Coding style can be verified using the project task runner
    3. Coding style can be applied using the project task runner
    4. Coding style has integration with relevant IDEs
    5. Coding style can be overridden using inline directives
    6. Project is set up to allow static analysis of the codebase via the task runner
  6. Logging
    1. Log events are emitted are different levels (TRACE, DEBUG, INFO, WARN, ERROR)
    2. Logs are structured (e.g. can be serialised to JSON)
    3. Logs are contextual (e.g. contain a correlation ID)
    4. Logs are emitted as streams (STDOUT, STDERR)
    5. Logging facility can be set or changed at runtime
  7. Documentation in repository
    1. Documentation is written in an appropriate textual format (e.g. Markdown, AsciiDoc)
    2. Installation, setup instructions are present (e.g. INSTALL)
    3. Project overview and description are present (e.g. README)
    4. Quickstart instructions available (e.g. list of 5 steps to get up and all tests running)
    5. Architecture or design documentation is present
    6. Historical decisions are present (e.g. ADR, Architecture Decision Records)
    7. Operational documentation present (supportability, fault mode descriptions)
    8. Developer support documentation present (e.g. specific instructions for re-creating production scenarios)
  8. Dependency management
    1. Dependencies declared
    2. Declaration has explicit dependency versions using SEMVER
    3. Declaration has dependency version integrity markers (e.g. checksum, signature)
    4. Separation between app and non-app (e.g. dev, tool) dependencies
    5. Conflict free use and upgrading of app and non-app dependencies
code