Docstrings considered too complicated

[Steven D'Aprano]

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 
be?

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 
that.


-- 
Steven