Meta

Ad hoc collection of software development practices organised by category.

Practice Guidelines

Practices should be given in general terms so as to be more widely applicable, e.g.:

  Prefer: All code should be under source control
  To:     Any code must be submitted to SVN server svn254.company.com for safekeeping

Label each practice with a unique ID. This can then be used as shorthand in code reviews.

Practices

Coding Standards

Use an existing well regarded coding standard e.g. the Google Java Style Guide.

Development Practices

[D01] All code should be under source control.

[D02] Write integration/acceptance level tests from the start of a project. This should enable the next practice [D03].

[D03] A component should be able to take production logs in a test for issue reproduction and fixing.

[D04] A component should be runnable from the developer's desktop. Preferably easily configurable in a simple main() method, otherwise, provide a launch file shared via source control.

[D05] Write components as libraries so they are easily instantiated and reused. Examples of different use cases would be: normal application startup, vs. test application feeding replay files for debugging.

[S-D06] [Suggestion] Add telemetry in from the beginning. This allows the set up of monitoring tools and alerting. Include GC telemetry in GC based languages/runtimes.

Coding Practices

Low level coding practices.

[C01] The most relevant code metric is code size. The smaller the program, the easier it should be to understand, and the less room for bugs to hide. (I don't say LOC, as this is easily gameable, just remove all line separators! But LOC can be a proxy for code size, when not abused.)

[C02] Following from [C01] above, code should be simple. Overly clever code, is just a recipe for mistakes. Simple concise code is certainly possible, look at examples from the JDK written by Joshua Bloch and Doug Lea, or the libraries from Martin Thompson, et al.

[C03] Treat warnings as errors. Zero tolerance for warnings. Do not litter code with @SupressWarning annotations just to bypass this practice.

[C04] To fix a production bug, always start by writing a unit/acceptance test to replicate it.

[C05] Tests for each feature or bug should be tagged with the relevant IDs from the issue tracking system for traceability.

Config Practices

[CF01] Declare the unit of the property in the value itself, then convert to required unit in the code, e.g.:

  Prefer: application.timeout = 2s # or 2 sec, or 2 seconds, …
  To:     application.timeout.milliseconds = 2000

[CF02] Encrypt production passwords.

Logging Practices

[L01] Prefer structured logs. Use "traditional" logging as way-markers, structured logs for debugging.

Testing Practices

Deployment Practices