Documentation should be versioned together with the thing it is documenting. I expect the documentation to be adjusted in the same Merge Request as the code. You might construe this to mean: “Oh, so you document everything in the code”. Nothing could be further from the truth, so if you’re curious to what I mean with this: keep reading.

My issue with code comments

Code comments, when done well, can improve the code by quite a margin. However, I’ve also seen a lot of bad code comments, often auto-generated unnecessarily increasing cognitive load.

I’ve often seen 2 opposing arguments on this topic (probably because nuance on Twitter seems to be impossible):

• “You should always document all your code”
• “Code comments are a scourge and should be avoided at all costs”

While I’m somewhere in the middle, I do have some aspects of documentation where I feel that code comments just fail to deliver.

For one, it’s hard to register bigger changes in concepts or structure in code comments. Code comments are local to a single file and can’t really contain diagrams (unless you are an ASCI-art professional). So if you change your class diagram, or you introduce an architectural concept like CQRS, no comment in code is going to make that clear to other developers.

Here is where a few people might say: “you should write and structure your code in such a way that those concepts (like CQRS) are evident”. The problem with this statement is that it is really hard to do this and already assumes developers know all the concepts up front. I’ve inherited some systems like this and let me tell you, even as an experienced developer, it is not a pleasant onboarding into a project.

My second problem with code comments is that they are restrictive towards non-technical users.

My problem with JIRA/Timetracking

• Loss after project?
• My brain is not event-sourced. I don’t wanna read all JIRA tickets to know what the system does.
• What is implemented when? (Commit message -> JIRA number)

My problem with Documentation in Confluence:

• Out of sync