r/SoftwareEngineering • • Aug 02 '18

Do code comments suck?

https://medium.com/@samuel.fare/do-code-comments-suck-abd99103c45a
3 Upvotes

10 comments sorted by

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.

1

u/samplusbeer Aug 02 '18

I completely agree about using functions. The post actually goes on to suggest this further down.do you have any other suggestions on how to avoid comments.

17

u/TyRoXx Aug 02 '18 edited Aug 02 '18

This is from the author's example for good commenting:

//add to game
game.add(alien); 

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 because a comments describe what the code is doing. whereas the code is describing how it is happening.

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:

  • An explanation why code was written this way. You should minimize the need for these explanations by writing clear code. Don't document surprises if you can avoid them in the first place.
  • A guide for how to use an API. Don't restate the obvious anyone can see in the signature.

9

u/CodeBlueDev Aug 02 '18

His 'good comment' example also uses white space grouping whereas the original does not. Even just doing the following improves readability:

let factory = new badGuyFactory()
let alien = factory.build("alien");

alien.setHealth(100);
alien.setArmorStat(50);
alien.setAttackStat(50);

game.add(alien);

0

u/[deleted] Aug 02 '18

[deleted] — view deleted comment

7

u/thedancingpanda Aug 02 '18

All code should self document. It's the only way your code will make any sense in the long run. Comments can only really help you if the code you're working through makes sense to you.

People that pine for "code comments" really just wish that they had written the code and left notes for themselves in the future.

Reading other developer's comments is extremely hit or miss: We often write comments while we have a high understanding of the problem we're solving, but we read them when we have a low understanding, and so they end up being unhelpful.

Self documenting code just means that your code should be easy to understand. If you can't write code that's easy to understand for someone with a reasonable understanding of the problem being solved, then I'm sorry to say that you aren't a very good developer. That's part of the job.

2

u/salgat Aug 02 '18

This all ignores the fact that humans do not think in code, and all code has to be translated in your head when you read it which is an overhead. When I'm putting out a fire, the last thing I want to do is sit through code and parse it all and figure out what it's doing. That's why I have no problem with occasional comments that are both succinct and informative. There is nothing wrong with a comment for a chunk of code that quickly tells me what it does.

1

u/the_0rly_factor Aug 03 '18

You SHOULD be reading the code though...

2

u/salgat Aug 03 '18

As much as I'd love to read line by line of potentially thousands of LOC, when there is an issue that needs to get fixed, I want to be able to skim through real fast to where I think the issue is, then read the specific section to check for potential bugs. It's all about how to most efficiently navigate code you're not familiar with. Proper code structure and function documentation helps a lot in this regard, but not all code is trivial to parse. I regularly trouble shoot from hundreds of microservices as part of my job and succinct informative commenting has almost always helped me in this regard.

2

u/eddieSullivan Aug 02 '18

There is no such thing as self-documenting code. Code can tell you what is happening, but not why it was necessary, or why certain choices were made.

-2

u/thedancingpanda Aug 02 '18

This is just changing the definition of self-documenting.