Clean Code Tip: Not all comments are bad
Many developers say that
All comments are bad! 💢
False! Most of the comments are bad!
For example, look at this method, and look at the comments:
|
1 2 3 |
<span class="token keyword">public</span> <span class="token return-type class-name"><span class="token keyword">bool</span></span> <span class="token function">IsPasswordValid</span><span class="token punctuation">(</span><span class="token class-name"><span class="token keyword">string</span></span> password<span class="token punctuation">)</span> <span class="token punctuation">{</span> <span class="token class-name">Regex</span> regex <span class="token operator">=</span> <span class="token keyword">new</span> <span class="token constructor-invocation class-name">Regex</span><span class="token punctuation">(</span><span class="token string">@"[a-z]{2,7}[1-9]{3,4}"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token class-name"><span class="token keyword">var</span></span> hasMatch <span class="token operator">=</span> regex<span class="token punctuation">.</span><span class="token function">IsMatch</span><span class="token punctuation">(</span>password<span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token keyword">return</span> hasMatch<span class="token punctuation">;</span> <span class="token punctuation">}</span> |
Here the comments are pointless – they just tell the same things you can infer by looking at the method signature: this method checks if the input string is a valid password.
So, yes, those kinds of comments are totally meaningless, and they should be avoided.
But still, there are cases when writing comments is pretty helpful.
|
1 2 3 |
<span class="token keyword">public</span> <span class="token return-type class-name"><span class="token keyword">bool</span></span> <span class="token function">IsPasswordValid</span><span class="token punctuation">(</span><span class="token class-name"><span class="token keyword">string</span></span> password<span class="token punctuation">)</span> <span class="token punctuation">{</span> <span class="token class-name">Regex</span> regex <span class="token operator">=</span> <span class="token keyword">new</span> <span class="token constructor-invocation class-name">Regex</span><span class="token punctuation">(</span><span class="token string">@"[a-z]{2,7}[1-9]{3,4}"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token keyword">return</span> regex<span class="token punctuation">.</span><span class="token function">IsMatch</span><span class="token punctuation">(</span>password<span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token punctuation">}</span> |
Here the purpose of the comment is not to explain what the method does (it’s already pretty explicit), but it explains with examples the Regular Expression used to validate the password. Another way to explain it is by adding tests that validate some input strings. In this way, you make sure that the documentation (aka the tests) is always aligned with the production code.
By the way, for more complex calculations, adding comments explaining WHY (and not HOW or WHAT) a piece of code does is a good way to help developers understand the code.
Another reason to add comments is to explain why a specific piece of code exists: examples are legal regulations, related work items, or references to where you’ve found that particular solution.
Conclusion
Always pay attention when writing comments: yes, they often just clutter the code. But they can really add value to the code, in some cases.
To read more about good and bad comments, here’s a well-detailed article you might like:
🔗 Clean code tips – comments and formatting
Happy coding!
🐧
Source: https://www.code4it.dev/cleancodetips/good-comments
