On 12/18/25 11: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.
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.
Since documentation never gets updated, if it's even created at all,
comments are the best you can get most of the time.
--
https://mail.python.org/mailman3//lists/python-list.python.org
