Docstrings considered too complicated
python at mrabarnett.plus.com
Sat Feb 27 04:25:47 CET 2010
Steven D'Aprano wrote:
> 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
Ah, yes, "apparently". That's like saying "someone down the pub told
More information about the Python-list