Now that you understand the need to document the code, let’s see when and when you don’t need to comment. In addition, I will also tell you how and what to comment on, remember that always following my personal judgment, “evidence-based” ;).
When to comment the code
As I said, on too many times I don’t see comments anywhere, but instead I do see comments where they don’t need to. What about this, how many times have you seen it?
/**
* Returns the id
*
* @return The id
*/
public int getId() {
return id;
}
Seriously? 5 lines of comments that don’t contribute to anything for 3 of code? This should not be commented on.
In general, anything that is obvious should not be commented on. Another example I find sometimes:
// Check if we still have work to do
if (!jobs.isEmpty()) {
// Get the next job for execution
Job job = jobs.getNext();
// Execute it
job.execute();
}
It’s obvious what that block of code does. Please don’t comment on that. Something that doesn’t add value to the code is irrelevant and even annoying in the eyes of some. However, if there’s a reason why your code isn’t that obvious, then don’t hesitate to comment on it.
if (!jobs.isEmpty()) {
// Not all the jobs will be in "jobs", depending on general config,
// some jobs will be also in "otherJobs"
Job job = jobs.getNext();
job.execute();
}
In this case, what is indicated is very relevant because one could go crazy trying to figure out why a job that should be pending execution is not running, and even debugging, why the job did not appear in “jobs”. A simple comment explains why and where we can find what we don’t see.
In general, whenever there is doubt whether something will be understood for one reason or another, it should be commented on. Commenting does no harm, IDEs allow you to put colors that do not disturb the purists, even some, such as VS Code, allow you to hide comments completely. Therefore, the code can be seen clean for those who hate comments. There are no longer valid reasons for purists not to comment!
Many developers tell me “it’s just that I comment in the end, when everything is already working, in case things need to be changed.” Don’t do that either: the result of that phrase is, invariably, that in the end that code will never be documented: few, very few exceptions have I seen to this rule. You will forget to do so, there will be other priorities to be made or any other excuse that prevents it.
Many may claim that writing comments on something that is finally undone to do something else is wasting time. Always remember this: documenting is never a waste of time, but an investment in maintenance. Any time you spend on documenting will be greatly multiplied in maintenance cost savings. If you’ve done something that at first seemed to be good but in the end it’s changed because it doesn’t work, maybe that kind of information is also interesting to leave it as documentation (for example, to avoid making the same mistake in the future).
What to comment on in the code
Basically, comment on anything that’s not obvious. And what’s obvious? It is true that, for everyone, the obvious is different depending on their level of knowledge. For me there are many things that are obvious, given my experience, but for a novice almost everything is strange.
Because they do, newbies are also going to see your code in a big company. And I can assure you it’s chaos when that happens, I’ve already lived it.
I would say that, removing the most logical, the patterns and basic common structures/mechanisms of the language being used (which, at least, that the novice should know), the rest should be commented on. Instead, advanced mechanisms, such as the use of sockets, should be briefly commented on so that a novice could easily assimilate it: no matter how much documentation there is of sockets, it is broad and complicated, a novice is lost among so much information. If you can give it the keys to what you use in a few lines, it would be better than have to read a full manual about sockets for a whole day.
In the next chapter I will show different examples to see what things should be commented on.
How to comment on the code
You also need to know how to comment. It’s not worth putting anything in, it must be something understandable, not too extensive, but not so brief that it doesn’t explain what’s necessary. Three lines of comments is a lot? It will depend on the complexity, there are times you need eight or more to explain well what is happening.
As I said, more important than what it does (you’re already seeing it in the code), it’s why and how.
With why you’ll understand the reason it was decided to do one thing and not another. It will help you understand the logic of the business, the paths that have been taken and its reasons.
for (k = 0; k < 8; k++) {
// returns black-white imbalance
applymask(k);
// current mask better than previous best?
if (x < y) y = x;
// To avoid redoing mask, don't increment i <--- Why and how reasons
if (t == 7) break;
}
With how you’ll get information that the code itself doesn’t give you. How am I getting this value? Why am I not using this other function that should, apparently, be better than the one there is? Maybe he had a bug at the time? You will also get information about the mindset of the person who made that code, that will help you understand the code.
function reload() {
// Load new user data from source instead of an specific cached model (what is the general rule) <--- How reason
// Do not use loadCacheModel() because cache is invalid. <--- Why reason
loadDataModel(user);
}
Variable and function names are also documentation
Have you ever found variable names like a, p1, p2, …? I do, and not always as instant-use auxiliary variables. It is ok to use the typical i, j, k for counters, but for the rest of the variables it is ideal for them to represent what they contain, even if it is an abbreviation of three or four letters. A single letter is too little to give info, and it’s also difficult to locate, visually, between lots of lines of code. Even with the code highlighting of IDEs.
With the functions it also happens. Sometimes we put on kilometer names, and sometimes names that don’t give any information. Names must be simple to understand and concise. And by concise I mean that they are not called getAuthenticationDetailsFromPreAuthenticatedUserDetailsSource, because such a name is, definitely, not concise.
The golden rule
Finally, there’s one thing that’s very, very important: never leave comments obsolete, update them if you update your code. There’s nothing worse than reading something in a comment and seeing something different in the code. The key to documenting the code is that the documentation is correct. And to be correct, everyone involved in development has to be committed to the principle of documenting the code.
This works such, e.g., SCRUM: it is not useful that only one apply the SCRUM methodology, the whole team and the client must adhere to it for it to work properly.
And since a picture is worth a thousand words, let’s see examples of things well and poorly done while documenting code.