Hacker News Reader

Comment by curioussavage | Hacker News Reader

I really don’t get the general attitude about comments that prevails. “Good code should be self explanatory” blah blah blah. As if “explains itself” weren’t a pretty damn wishy washy and relative guideline.

And I’ll push back against absolutist arguments about never writing about the “what” too.

So much moaning and whining about the possibility that the comment might get out of sync with the code. Oooh so scary.

Lazy reviewers are the real problem there.

At this point I’m almost a specialist in doing deep dives and deciphering what spaghetti code is actually doing and why. And I make damn sure to write comments to help out the next poor soul.

View on HN

Yeah, code gets rewritten a lot because there's a intentional lack of documentation. Not entirely sure how people decided that comments are bad or that commenting is more harmful than not.

This may just be me but does anyone else actually enjoy documenting their code?

You can always make your code self explanatory, but the cost in abstraction and maintenance results sometimes a negative ROI. In such cases, writting comments is often the best solution.

There's some excitment in identifying those, and that's where I enjoy documenting the intention of my code.

>You can always make your code self explanatory

this code is done in this way because EU regulation #1374 regarding Maritime tracing.

this code seems inefficient and silly but is that way to get around a specific rendering issue in Opera Mini which needs to be supported because our project needs to support basically everything because it is a required governmental service.

This code is dealing with an issue in Safari that is supposed to be fixed by June 2024 release - please check if it is still an issue - test by doing the following...

Tldr: No, you can not always make your code self-explanatory.

I enjoy commenting the code if it needs it

> As if “explains itself” weren’t a pretty damn wishy washy and relative guideline

No more wishy-washy than the concept of a comment explaining code.

> At this point I’m almost a specialist in doing deep dives and deciphering what spaghetti code is actually doing and why.

I don't always read comments. But when I do, it's after reading the code.

Clean code talks about this very well. Like all things it's a matter of doing it write or wrong.

The checklist includes:

1 are you using comments to manage obfuscated code? I.e. the comment isn't the problem it's the spaghetti code it makes the person feel entitled to write after