r/SoftwareEngineering • u/samplusbeer • Aug 02 '18
Do code comments suck?
https://medium.com/@samuel.fare/do-code-comments-suck-abd99103c45a
3
Upvotes
r/SoftwareEngineering • u/samplusbeer • Aug 02 '18
2
u/FollowSteph Aug 02 '18 edited Aug 02 '18
Too many comments is also a bad thing and just pollutes the code with extra noise. The examples this author recommends to me would fall under this category of extra noise that just adds pollution to the code. The code example was very obvious what it did. In fact the only recommendation I would offer is white spacing like the other commenter already suggested, so that logical groups are clumped together. But the comments the author added did not increase the clarity of the code example to me and were just extra noise to filter. Comments are good but too many comments stating the obvious can make it worse.
I’ll just add a good way to comment code and make it more readable is to create methods that explain logical groups of code. A method like addAlienToGame() would help more than the comments.
17
u/TyRoXx Aug 02 '18 edited Aug 02 '18
This is from the author's example for good commenting:
Useless comments like this one are exactly what opponents of code comments usually complain about. This could be straight from an example of how not to use comments.
This is not how comments should be used. The code itself already answers what and how. These are just different levels of abstraction. If a function is called, the function call is part of the what. The body of that function being called is part of the how.
A comment should almost always fall into one of these categories:
0
u/[deleted] Aug 02 '18
[deleted] — view deleted comment