Day 18 of #100DaysOfCode
Don’t comment your code, Rewrite it!
Don’t spend time writing comments, spend time cleaning your code
We are taught to write comments in code in the very introductory part of some programming classes and then we quickly jump into real coding concepts. We treat comments quite lightly and we use them carelessly all over the code.
If you browse through some of my older codebases, you would find comments which are explaining what function is doing, what argument it takes what value it returns. If you read the previous story about naming functions and variables correctly, you know writing comments to explain your code would be unnecessary. Only for special exceptions, you are allowed to write comments.
“Don’t comment bad code explaining what is happening, Rewrite it!”
There often would be times when you write code, you write a very good comment explaining it with some very good intent. After some time, you are required to make some changes to this function, you would come back to this function quickly make changes and resume with your current task.
This makes things even worse! Inaccurate comments. It’s better to have no comments than misleading comments. They set expectations that are never fulfilled, they set up some ground rules which are never required to be followed.
“Code never lies, comment sometimes do”
Comments are not responsible for explaining your badly written code. We write modules which we know are complex, we know they are a mess. “Ooh, I’d better comment that!” No! You’d better clean it!
Don’t spend time writing comments, spend time to clean up the code. For example,
// Checking if student is eligible for scholarship
if (student.result & (student.age < 18) & STUDENT_FLAG) {
...
}“The only best comment is the comment you found a way not to write.”
if (isEligibleForSchorlarship(student)) {
...
}private fun isEligibleForSchorlarship(Student student): Boolean {
return (student.result & (student.age < 18) & STUDENT_FLAG)
}
There sometimes are comments which just state the obvious. We call them Noise comments.
class NetworkingRepo {
/**
* Network status variable
*/
public boolean networkStatus
/**
* Default Constructor
*/
public NetowrkingRepo() {
}
/**
* Closes all active connections
*/
protected closeActiveConnections() {
...
}
}I have been a victim of misleading comments which I wrote myself. Here is one of my personal examples, after a lot of writing, deleting and rewriting my code one block of my code was looking like this.
The code was either moved/deleted but its comment was still there which seems like explaining what the below function is doing which wasn’t the case at all.
Then there are scenarios where we comment out some code. Never do this! Others who see the commented out code won’t have the courage to delete it. They think it's still there for some reason and hence will always be there haunting devs.
And finally, for some exceptional cases, you are still writing comments. Make sure your comment clearly explains all the complexity of the code in the most simples words. Your comment shouldn’t need an explanation of itself.
Closing up with one of my favorite quotes,
“Real Programmers Don’t Comment Their Code, If it was hard to write, it should be hard to understand” 😂
If you liked this story around clean code, make sure you check out my other two stories on Clean Code. These are amazing, you will get to learn a lot!
Thanks for reading and as always you are breathtaking ❤
