Docstrings considered too complicated

Steven D'Aprano steve at
Sat Feb 27 01:02:40 CET 2010

On Fri, 26 Feb 2010 09:09:36 -0600, Tim Daneliuk wrote:

> Reminiscent of:
> mov  AX,BX               ; Move the contents of BX into AX

That's a *good* comment, because without it most English-speaking people 
would assume you were moving the contents of AX into BX.

> And, yes, I've actually seen that as well as:
> ; This is a comment

Which might be a good comment, if it were part of an unfamiliar file 
format where the reader were not expected to know what is a comment and 
what is significant. For instance, I've seen similar comments at the top 
of config files.

However, I'm pretty sure that a comment like this is inexcusable:

x = x + 1  # Add one to x.


More information about the Python-list mailing list