6 ms·

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 p

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.

raytopia 3y ago
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?
- jspdown 3y ago
  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.
  - bryanrasmussen 3y ago
    >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.
- bryanrasmussen 3y ago
  I enjoy commenting the code if it needs it
cwalv 3y ago
> 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.
dmarchand90 3y ago
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 2 can the code just be a function with a clear name 3. Is the comment a non comment ? <some others I forget the book is a great read> That said. Plenty of times you need a good comment.
mrkeen 3y ago
> 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.

raytopia 3y ago

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?

jspdown 3y ago
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.
- bryanrasmussen 3y ago
  >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.
bryanrasmussen 3y ago
I enjoy commenting the code if it needs it

cwalv 3y ago

> 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.

dmarchand90 3y ago

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 2 can the code just be a function with a clear name 3. Is the comment a non comment ? <some others I forget the book is a great read> That said. Plenty of times you need a good comment.

mrkeen 3y ago

> 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.