Docstrings considered too complicated

[MRAB]

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 
> 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.
> 
Ah, yes, "apparently". That's like saying "someone down the pub told
me...". ;-)