Each codebase must be understandable and easy to change by new developers with minimal experience of the application


Systems become unmaintainable through size, complexity and lack of up to date documentation. By keeping our components small and well tested we reduce complexity and increase maintainability. By combining these small, well understood components we are able to create large, complex yet maintainable systems


  • Software must be created with a comprehensive suite of tests that can be run from the command line with a single command.
  • Appropriate levels of documentation will need to be created and updated, with a preference for it to be enshrined in code as tests.
  • Different audiences may require different artefacts for effective maintenance. This may include, the code, the commit history, JIRA or formal documentation.
  • Stale documentation is worse than no documentation, so therefore investment will be required to ensure it is up to date.
  • Knowledge transfer can be split into two parts, the 'WHATS' and the 'WHYS'. The WHATS should be evident from the code but the WHYS should be carefully documented. Code comments and/or appropriately named tests can be useful in this case. Handover of the WHYS should be done to all levels, not just to developers.
  • README's should be created describing the application and documenting the command required to build, test and run the application
  • Each codebase should have a published set of code style guidelines, preferably importable into your IDE or text editor. At a minimum, encoding, linebreaks and tabbing standards should be defined (take a look at editorconfig).
  • Developers should refactor code and tests when needed, reassured by the presence of the rapid feedback they will receive if they break something


  • Clean Code will be used as the starting point for what defines 'Clean'
  • Small systems help a lot here.
  • Keeping documentation with the code. Tests, swaggerfox. Examples are Payment
  • Although these examples are from a particular context, they could easily be adapted for recording any decision or system info / rationale
  • Lightweight Architecture Decision Records
  • Decision record template / advice being trialled
  • OCCO Architecture "agile documentation principles" (see attachment). Idea is to produce wiki reference docs that are always current - accessible to everyone for reads, but more careful with trust and quality checks for updates.
  • OCCO also logs key decisions / rationales (business and IT) in JIRA with specific ticket types. Quality is variable but has proven its value many times over the last few years.

Points for discussion

  • If a new person joins, can they get up to speed quickly?
  • Can code be safely refactored due to good test coverage?

results matching ""

    No results matching ""