Documentation and tests

It is one of those fallacies I’ve argued against for too long with too many people - “if your code is written well enough, it should not need documentation, and it should not need tests.” My experience has been that anyone who makes this kind of statement writes code which is overly complex and, therefore, prone to obscure issues. If anyone needs to write tests, it’s people who think their code is too good to need documentation or tests.

Documentation

Even if you feel that your system is well-architected and coded cleanly, it should be clear what the moving parts are for, and I shouldn’t need to read and understand your code to use it. I should be able to read your documentation and then use your API without having any inside knowledge of your system.

There has been a trend away from Confluence to things like Gitlab Pages for documentation of services. This is entirely understandable as, in many cases, the documentation should live with the code it relates to. Also, one would assume that the git server is essential to the organisation and, therefore, is backed up and made highly available. On the other hand, I have worked with more than one client where the GitLab server, for example, is not correctly supported to a level where it is kept up and running and accessible to the devs at all times. This will eventually be an issue, which will no doubt be in the middle of the night. This is one of the main things which is always running through my head when looking at implementing new system components, even down to the level of GitLab - what will happen if this goes down in the middle of the night!?

Architecture Diagrams

I love a diagram. The map is not the territory, of course, but it is nice to have a map. And really, several maps. At the end of the day, as in this diagram from Snafucatchers, The System is defined by people's perception of The System, and diagrams are a great way to document and collaborate on defining that perception.

I like to see a diagram of the whole architecture of the system. Then, a separate one which shows the dependencies for the part of the system the team is responsible for - usually, this is a particular service or group of services. I also like a diagram of all the moving parts - if you don’t have this already, LucidScale gives a good overview of whatever you have deployed on AWS or Azure.

Automated build and test via pipelines

It would be best if you automated your pipelines. The best way to do this is to read the Continuous Delivery book and treat it as a todo list. Matthew Skelton has been saying this for so long that I’ve forgotten when I first heard him say it. Really, really, really, make sure that you don’t add in any F-ing manual processes ‘just this once’. If you do, you’ll regret it. As NATS have shown us recently, a manual process can take exponentially longer than an automated one, and you will eventually try to skip the manual step if possible. I am very old school regarding the build and packaging steps, too - if you completely rebuild your artefact between test phases, you are testing a different thing. Don’t do that - build it once and push it through environments. Octopus Deploy is still the best thing I’ve seen for managing that ‘push it through’ process.

Lint, unit, integration, and end-to-end tests

The main thing to automate in your pipelines is your tests. It’s essential to have a linting, formatting and standardisation process, and it needs to be something which can be run by a developer locally before check-in. There’s nothing worse than having to check your code in so that you can see whether you have an additional space in your code. You should know what a test pyramid is and try to stick to it.

In conclusion, documentation and tests are vital components of software development. While well-written code is necessary, relying solely on code quality without proper documentation and testing can lead to issues and difficulties for users. Documentation helps users understand the system and its functionalities without diving into the code, while tests ensure that the code functions correctly and remains reliable. Automating pipelines and incorporating linting, unit, integration, and end-to-end tests is crucial to maintain code quality and streamline the development process. By prioritising documentation and tests, developers can enhance The System's usability, stability, and maintainability.