602
No comment
(lemmy.nz)
you are viewing a single comment's thread
view the rest of the comments
view the rest of the comments
this post was submitted on 25 Sep 2026
602 points (98.9% liked)
Programming Humor
3503 readers
1 users here now
Related Communities !programmerhumor@lemmy.ml !programmer_humor@programming.dev !programmerhumor@kbin.social !programming_horror@programming.dev
Other Programming Communities !programming@beehaw.org !programming@programming.dev !programming@lemmy.ml !programming@kbin.social !learn_programming@programming.dev !functional_programming@programming.dev !embedded_prog@lemmy.ml
founded 3 years ago
MODERATORS
Code commenting has gone through different phases over the years. Back when many languages weren't very readable, it was important to use comments. We've migrated mostly to self-documenting code, but I've never left them completely behind.
As an example, I do a fair bit of SCAD work. It's a functional language that is often not obvious--many commands are repetitive. So I'll often use headers at the least.
Even working in C, I'll often document things about parameters and return values so that I don't have to read through the code when I go to use the function. They have their place, but if you have more comments than code, that's a bad smell.
Fair, I'll make an allowance for doxygen/javadoc style tagged comments in low level languages and for libraries where you don't expect people to read the implementation
How do you know the comments are correct, or that they have been maintained along with the code over the years?
If you don't know or trust the author, you don't know whether they're correct. And if something doesn't compile or there ends up being issues, you might have to read through the code more carefully to figure out what's going on.
But if you don't know or trust the author of self-documenting code, you can still run into the same issues. Comments are just another part of the code.
Comments are by definition not part of the code.
And no, I never trust the author - even if it was me 6 months ago.
Not to mention all the other programmers that might have fiddled with it. Not mention changes in the code since it was written, where the comments weren't updated.
As a maintenance programmer with 35 years experience, the first thing I do is delete the comments. My experience says they get in the way and can't be trusted. Read the code, understand the code, and figure why it's doing what it's doing. Don't worry about what it might have been doing 10 revisions ago when the comments were last updated.