The code is its own documentation
You heard this before: “The code should be its own documentation”. I don’t like this phrase. There is some truth to it, but I don’t feel it’s completely accurate. It misses some cases where the code is not, and should not, be its own documentation.
Table of Contents
When the code is the documentation?
Documentation adds complexity to code.
Documentation is just another form of complexity for your project. It needs to be read and understood and maintained. And like everything else, you need to apply your time on the most valuable tasks.
The code should be as streamlined as possible.
Me, as a reader, I want to spend as little effort as possible to understand the code. I have a problem I’m trying to solve, and I want to focus as much energy as possible to figure out the solution, and as little as possible to understand the file I’m working with.
To be clear, you should understand the code that you are working with. What I am saying is the code should be written in such a way that makes understanding it easier.
Writing simple code is hard.
It’s not easy to write code that is easy to read. It takes experience and time and energy, and sometimes more than one attempt. The goal should always be to make the code as simple as possible without sacrificing performance, just make sure documentation does not get in the way.
When the code is not the documentation ?
Sometimes life is messy and business rules even more so. The rules were made before you joined the project and for some archaic reason that has nothing to do with you, they must remain as they are.
The code is not very good at providing context.
Sometimes you have to do unexpected things, or build some really complex logic to follow some particular set of business rules. This is the time when you have to roll up your sleeves and update that documentation.
Let's take an example. Say the business you work with decided to acquire a similar business and keep it running under the same brand. They want to use the same backend system to keep track of both branches, but the packages they offer vary slightly in name and details. The code on its own cannot provide enough context. It’s good practice to put all the rules around the split between businesses somewhere it can be accessed by a new member joining the team.
Why should I care ?
Documenting a project is a difficult task, it takes time and effort that would otherwise be spent delivering a feature, or at least playing some fun computer games. It’s about making sure you spend your time efficiently and you add value (including with documentation).
Documentation should compliment your project, be a place for complex decisions to live and be visible to the development team, it should not add unnecessary complexity and make the project harder to understand than it already is.