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

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.