Docstrings considered too complicated
steve at REMOVE-THIS-cybersource.com.au
Sat Feb 27 04:15:47 CET 2010
On Fri, 26 Feb 2010 18:47:26 -0600, John Bokma wrote:
> Steven D'Aprano <steve at REMOVE-THIS-cybersource.com.au> writes:
>> 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.
> Eh? It's a bad comment, it's of the same quality as:
>> x = x + 1 # Add one to x.
> You think the former is good because (I guess) you are not familiar with
> the language. The same reason why beginners comment their code like in
> your example.
Well, in the second example, x+1 could not possibly be anything other
than adding one to x in any language, programming or human: using "+" for
addition is close enough to universal these days. Unless x is some fancy
object that plays operator overloading tricks, then what else could x+1
On the other hand, mv AX,BX is not only ambiguous but in the example
given the move occurs in the counter-intuitive direction, at least for
English-speakers and probably most speakers of European languages. So
even an experienced coder might like the reminder that this specific
assembly language moves things backwards compared to his intuition, or
compared to the way the rest of the language does things.
Admittedly an experienced coder might be so used to that syntax that he
no longer needs the comment, in which case he might find it unnecessary.
But comments aren't written for the benefit of people who find it
obvious. They're written for everyone else. ANY comment could be
dismissed as unnecessary for somebody who is so familiar with the
language and code in question that it is obvious what it is doing.
Also, some assemblies perform the move in different directions according
to the arguments. So you might have:
mv AX,BX ; move contents of BX into AX
mv @CX,DX ; move contents of @CX into DX
Horrible, yes, but apparently some assembly languages did something like
More information about the Python-list