Stop Writing Code CommentsBrian NorlanderBlockedUnblockFollowFollowingMay 15“Clean code should read like well-written prose” — Robert C.
MartinStop writing code comments.
There is usually a high correlation between bad code and code with a lot of comments.
This is the most obvious sign of messy source code.
The goal of every programmer should be to write code so clean and expressive that code comments are unnecessary.
The purpose of every variable, function and class should be implicit in its name and structure.
When you need to write a comment, it usually means that you have failed to write code that was expressive enough.
You should feel a sharp pain in your stomach every time you write a comment.
When someone else reads your code, they should not have to read the comments to understand what your code is doing.
Well named classes and functions should guide the reader through your code like a well-written novel.
When the reader looks at a new class or function they should not be surprised by what they see inside.
Remember, very little of a developers work time is actually spent writing code, much more time is spent on reading code and understanding what it does.
Comments Cover Up FailuresI often see comments above variable or function names describing what the code does (or is supposed to do).
These comments make it clear that the programmer was not able to think of an expressive enough name or that their function is doing more than one thing.
Naming things is your code is extremely important.
You should put a lot of effort into naming every piece of code accurately and precisely so that other developers can understand your code.
In this example, the name find was not descriptive enough, so the author of this function needed to leave behind a descriptive comment describing what the function does.
When we see the find function called from another module, it is a mystery what it does.
What is it finding?.What exactly does finding mean?.Is it returning what it finds?.How is it finding whatever it finds?.Like Uncle Bob says in his book Clean Code, if you need to write a comment you have failed to express yourself through your code.
We don’t want to have to examine the comment above each function to understand what it does.
Now it is obvious what this function does just by reading its signature, which makes the comment redundant.
This brings me to the next way comments are failures.
Redundant CommentsThese clutter up your code and are completely unnecessary.
Adding many redundant comments trains the reader to skip over every comment, so when there is a comment that is important it will likely not be read.
The last example is mandated redundancy.
Many organizations require this above every function and class.
If your boss requires this, ask them not to.
Wrong Level of AbstractionIf you have a long function or need to document which part of your code does what, then you might be violating these rules:Functions should do one thing.
Functions should be small.
Here is an exampleIf you have pieces of code that can be separated into their own functions, then refactor it.
When you have successfully encapsulated each portion of logic into a separate function, the code should read like a description of what it does.
Refactored we have this:Instead of commenting each part of your code, each chunk of logic should be nicely encapsulated in its own function.
First, this improves readability.
Each chunk of code does not have to be read line by line.
We can instead simply read the helper function name and understand what it does.
If we want to know further details inside each function, we can always see the implementation.
Secondly, it improves testability.
In our example above, we can make a separate test for each function.
Without encapsulating these separate functions it is difficult to test each part of the larger function sendPromotionEmailToUsers().
Functions that do more than one thing are hard to test.
Lastly, it improves refactorability.
By encapsulating each part of the logic into its own function, future changes will be easier to do and will be isolated to changing the behavior of that function only.
When we have long functions with local variables that persist throughout the entirety of the function, it is hard to refactor the function without causing changes somewhere else because of how tightly coupled the function is.
Commented Out CodeCommented out code should be treated like roadkill.
Don’t look at it, don’t smell it, don’t ask where it came from, just get rid of it.
The longer you keep it there, the longer it makes the rest of the code smell.
If you try to uncomment the code, who knows if it will even compile?.Will that section of code invalidate something else in the code?.Just delete it.
If you need it later, you can always check your Version Control System, because you are using a VCS, right?TODO CommentsDon’t write TODO comments, instead maybe just… do it?.Most of the time these comments get forgotten about and later on might become irrelevant or wrong.
When another coder sees the TODO comment later on, how do they know if this still needs to be done?.Delete these comments too.
The only time a TODO comment is ok is if you are waiting for a merge from another teammate.
This is not meant to last a long time, just until you can make the fix and submit it.
“When you feel the need to write a comment, first try to refactor the code so that any comment becomes superfluous.
” — Martin FowlerComments LieAnother problem with comments is that they lie to us.
When Jimmy makes a comment above the new function he wrote, he thinks he is helping out any future developer that sees his code.
What he is really doing is setting a trap.
His comment may lie (no pun intended) dormant for months or years not being touched, just waiting to become a nasty lie.
Then one day during one of the hundreds of refactors and requirement changes, his comment becomes invalidated from some far away module.
When you change a line of code, how do you know you didn’t just invalidate a comment somewhere else in the code?.There is no way to no.
Comments must rot.
Then later on a developer wants to split name into firstName and lastName.
Bam!.The comment is now wrong.
You could update the comment to reflect the changes, but do you really want to manually maintain all of your comments after each change?.You are a developer, not a documentor.
But this comment is easy to notice and is no problem to change.
Let’s see another example:Later on someone changes the function findEmployees so that it finds employees by a list of names instead of a list of statuses.
First, the comment above findEmployees has been invalidated, so that needs to be changed.
No problem, right?. More details