On 19/12/2025 08:52, Peter Flass wrote:
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.
Are your unit and integration tests a form of (technical) documentation
and a guide for use?
If start from the spec/user story (perhaps as a README.md in tests/) and
reproduce appropriate sections (as comments/docstrings, hah!) in each
test file, then will all flow-through?
--
Regards,
=dn
--
https://mail.python.org/mailman3//lists/python-list.python.org
