Photo by Kristina Flour on Unsplash
No Comments Please!
The Art of Commentative Coding without Comments.
Table of contents
The Motivation:
Let's say, you see this code:
// Wake the minion up if he's sleeping
if ( minion.getStatus() == 2 ) {
minion.wakeUp();
}
Without the comment, it's probably not quite obvious what the integer "2" means!
And rather than having to rely on comments, we could do better by introducing a variable, like so:
int SLEEPING = 2;
if ( minion.getStatus() == SLEEPING ) {
minion.wakeUp();
}
The code now reads like a comment. Doesn't this make it more effective while articulating what the code intends to do?
Another, yet more complex if statement:
// Go to sleep if minion has been awake for at least 8 hours or if he's tired and has been awake for at least 4 hours
if ( minion.getStatus() == AWAKE && (currentTime() - minion.getLastAwake()).hours >= 8
|| ( minion.getStatus() == TIRED && (currentTime() - minion.getLastAwake()).hours >= 4) {
minion.sleep();
}
Simplifying and refactoring, you could remove the comment:
boolean minionIsAwakeForAtLeastEightHours = minion.getStatus() == AWAKE && (currentTime() - minion.getLastAwake()).hours >= 8;
boolean minionIsTired = minion.getStatus() == TIRED;
boolean minionIsAwakeForAtLeastFourHours = (currentTime() - minion.getLastAwake()).hours >= 4;
if ( minionIsAwakeForEightHours || ( minionIsTired && minionIsAwakeForAtLeastFourHours)) {
minion.sleep();
}
OR, alternatively, if the conditions are far more complex, you could refactor them into a function:
if ( minionCanSleep(minion) ) {
minion.sleep();
}
....
boolean minionCanSleep(minion) {
boolean minionIsAwakeForAtLeastEightHours = minion.getStatus() == AWAKE && (currentTime() - minion.getLastAwake()).hours >= 8;
boolean minionIsTired = minion.getStatus() == TIRED;
boolean minionIsAwakeForAtLeastFourHours = (currentTime() - minion.getLastAwake()).hours >= 4;
return minionIsAwakeForEightHours || ( minionIsTired && minionIsAwakeForAtLeastFourHours);
}
The Argument:
You may argue, "Why not write high-quality code and write comments too? Isn't that better? Comments are supplementary anyway." Well, the problem is comments get bugs like code. People often change the code but not the comments that surround them, hence the problem of comments that don't match the code, turning the world of developers into a spiral of what's reality?!
Unlike comments, we have tools to stop bugs from getting into the code. Tests! Compiler Checks! Linting! And so many more!
"Comments can lie, but code can not!"
The Not-Guilty:
Having said that, code documentation is different from the code comments. Documentations like JavaDocs and API Specifications (Swagger) describe how code is used rather than stating how code works.
Of course, there are always exceptions too. For example, if the intention of the code is not obvious, maybe for performance reasons or references to some algorithms for maintainability, comments generally would do better than not.
Moral of the Story:
"If the code seems complex enough to warrant a comment, you should see if you could simplify and refactor to make it better instead."