No Comments Please!
The Art of Commentative Coding without Comments.

I am and by heart a technology enthusiast, keen on every crazy stuff that technology has come to offer. I try and develop whatever makes life easy (and with some style!), and hopefully make people smile - I guess that’s the essence of technology!
Been working as a Software Engineer predominantly in Java Backend services and solutions for over 6 years, and with professional knowledge on frontend technologies as well, I have worked on several websites and web-applications, putting down wireframes to implementations.
I have a really diverse set of skills (owing to my wild interests rampant all over the place), ranging from design, sketching up logos, illustrations, UI, backend system designs and solutions, scaling up performances, etc.
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."


