Docstrings considered too complicated

[Steven D'Aprano]

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.



-- 
Steven