Python-list Digest, Vol 92, Issue 223

[Richard Parker]

> 
> On Thu, May 26, 2011 at 10:58 AM, Richard Parker
> <r.richardparker at comcast.net> wrote:
>> It's time to stop having flame wars about languages and embrace programmers
>> who care enough about possible future readers of their code to thoroughly
>> comment it. Comments are far more valuable than the actual language in which
>> the code is written, IMHO.
> 
> The problem with comments (and documentation in general) is that they
> are often imperfect. If the code is absolutely opaque but it has a
> comment next to it, you still have that niggling doubt: has the
> comment been updated whenever the code has? Was it even accurate in
> the first place? (Comments often say what a piece of code _ought_ to
> do, but the code might have a bug in it. And sometimes, that bug ends
> up being part of the function's definition, and people depend on it.)
> I'd rather have both - reasonably readable code AND a comment, where
> the comment explains the intent behind the code.

Gee...I absolutely agree! I have no problem with anything you said. My intent in writing at all was to express that comments (along with well-written code) are more important than the language in which the code is written. There's no doubt that sometimes comments aren't updated when code is changed and sometimes comments express what the code is attempting to implement; however, code in any language written without accompanying comments is much harder to understand AND maintain. If, given a chunk of readable Python code written by someone else without accompanying comments, I would be scratching my head far longer trying to understand, modify, or maintain it, than if it also had (even imperfect) accompanying comments.

So--we agree that reasonably readable code AND a comment that explains the intent of the code is what we should all strive to produce.

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-list/attachments/20110525/f95a69f1/attachment.html>