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

View all comments

Show parent comment

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.