On 12/18/25 13:00, Richard Kettlewell wrote:
Peter Flass <[email protected]> writes:
I comment *A LOT*. When I had to go back and revisit some very old
code, I wished I had commented more. I've almost never looked at a
program and said "I wish it had fewer comments."
Regrettably, I’ve encountered plenty of comments that don’t actually
reflect the code (for a variety of reasons).
If the code is wrong and the comment is right then that’s great, you
have a nice hint about how to fix the code, assuming you realize there’s
a problem at all.
This is why you don't just blindly cut-n-paste "helpful
code" you find on the net :-)
Often were several versions of it ... but nobody bothered
to update the comments.
However if the code is right but the comment is wrong then the comment
is worse than nothing. The code would be improved by removing it
(although almost certainly improved even more by correcting it).
I’ve also encountered quite a few comments written by people who had
been instructed to add comments to under-commented code, but didn’t
really understand what they were looking at. The result generally
obscures more than it illuminates.
If the actual code WRITER doesn't understand his/her/its
own code ... that's worrisome.
As I mentioned to someone else, I've got a Python function
around somewhere with about SIX lines of actual code and
over THIRTY lines of comment above it explaining why the
tricky little devil works.
--
https://mail.python.org/mailman3//lists/python-list.python.org
