2 min read

20. Why In-Code Comments Are Crucial To Code Maintainability And Health

Have compassion for those who will maintain your code.
20. Why In-Code Comments Are Crucial To Code Maintainability And Health
Photo by Markus Spiske / Unsplash

Comments are documentation. A well-written codebase should be self-explanatory through the code and its comments. Too often, in-code documentation is missing. In Golang tooling, that is an annoying aspect I appreciate: it throws warnings if exported types do not have comments:

"Exported type should have comment or be unexported"

Sometimes, developers will insert a useless placeholder comment to quiet the linter. But really, this is where we should stop and think about how future developers will read our code. Current engineers know what they are doing, especially when they spend so much time on the same code for weeks. However, new devs, no matter how smart they are, may lack the prerequisite context to decipher undocumented code. It can be done, but for most, it is an unpleasant experience. The disinterest of some developers to comment their code properly can negatively impact future engineers as well as the same devs, especially when they have to, years later, fix a bug they mistakenly introduced.

Not documenting code may make a code-review faster as the reviewers may also not want to spend too much time on it. That is a mistake. It will increase the friction required to understand the code, decrease developer enthusiasm and increase development time.

There is a middle ground to how much documentation is required, not too much and not too little. Less is more only if it contains as much information and is as understandable as a longer explanation. While being parsimonious, one should always assume that a reasonably intelligent but domain-inept developer will at some point be onboarded and asked to maintain and expand the codebase.

The reality is that most software engineers switch domains multiple times in their careers. For many of us, writing and designing code is our expertise but the domain is not. It can be arduous to understand why some part of the code does what it does when we lack that domain familiarity. Financial, defence, e-commerce, medical, aviation...each represents a new complex domain to grasp in order to implement effective code in that field.

When a new developer joins our team with no domain familiarity and our code has poor to non-existing commenting, they demand much attention from the other devs. While some senior devs may feel pestered, that is a result of the coding and documentation paradigm espoused by their team. There is a distinction between a lazy engineer who does not go through the due diligent process of understanding a codebase, and one who did and still does not understand a part of the code or design decisions.

That is why, as software engineers, we must push for clarity not only in our code naming, but also in our comments. We must remember that others will tread in our shoes, and our responsibility is to create a codebase our future colleagues will be able to maintain.