What’s the point of documenting the code? Is it necessary? Don’t some purists say it’s not necessary to document the code if it’s well written? Let’s resolve these doubts briefly, before we begin.
What some purists say about the code and its comments
Many people defend the code “as clean as possible”, including this do not setup comments. For them, the code must be self-explanatory. If you don’t understand what you’re doing, then you have to write better self-explaining code.
In this last part I agree. The code should be clear in what it does, it should be easy to understand. For example, this code does not need explanation beyond explaining what it was created for (what is done in the header), it is entirely clear what it does:
// Get the default language for the app
export class LanguageService {
private supportedLanguages = ['es', 'en'];
private defaultLanguage = 'es';
constructor(public translate: TranslateService) {}
getLanguage(): string {
const userLanguage = this.translate.getBrowserLang();
return this.supportedLanguages.includes(userLanguage) ? userLanguage : this.defaultLanguage;
}
}
But if we already know what the code does, why do we want to comment on it?
The key word here is what. The problem is that we lack two more keywords to understand the whole set: how and why.
I’ll ask you a question: when was the last time you were given up-to-date and complete project documentation before you have to work on it? I will tell you about my experience: I believe that once in my entire career, and not because I have collaborated on few projects.
Maintaining documentation about any project that is alive is extremely complicated, because today applications are not like 40 years ago, with a unique purpose, well defined and not prone to changes. On the other hand, I think I only know one person who reads dozens of sheets of documentation from a project before he gets to work on it, and he’s older than me. No, it’s not the norm.
The usual circuit of a developer who is hired in small and large companies (or at least the ones I have seen by myself and by others) is: we will put you in project X, talk to John that will give you all the information you need.
Then you talk to John and he gives you some guidelines, accompanies you on the first day to set up the environment, gives you access to the files and indicates your task. From there, they give you a task and… If you have any questions, ask. Documentation? There was one at start, but it’s obsolete, you better not look at it.
Well, you’re already in the hassle, you start to see the code of what you have to modify/expand and you don’t understand anything. Why do they call this show here and not there? What is this three-letter global variable for? How did you get this data? None of this is explained anywhere. And if the one who did it didn’t comment on the code, then it’s time to analyze the code step by step and see what he’s doing and try to figure out whys. It’s almost reverse engineering: getting from code to detailed specifications.
You just found out, the hard way, why we need to document the source code. Nobody’s going to read the documentation outside the code. But the code will be seen by everyone who has to modify it. In addition, it will always be updated code, so it is important that the comments are also updated. If your code is documented:
- You’ll be able to remember how your code worked long after you created it.
- Another will know what your code does and why, without having to decrypt it.
- You’ll be able to know what a complex block of code does without having to analyze a line, just by read it in the comments.
- You’ll be able to find out why a specific feature you’d use today was not used (maybe I had a bug at the time?).
- You can rule out other solutions that have been tested before but that had some problems (they may seem obvious at first but had some drawbacks).
So you need to document the code?
If you want to be able to upkeep the program without going crazy in the future (or that others become), definitely yes.