Re: Python

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