On 2/26/2010 9:25 PM, MRAB wrote:
> Steven D'Aprano wrote:
>> On Fri, 26 Feb 2010 18:47:26 -0600, John Bokma wrote:
>>
>>> Steven D'Aprano <st...@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...". ;-)
It's interesting that my silly example raised this amount of
commentary. My general view about all this is that comments should be
written on the assumption that the reader knows the language in
question. It is not the purpose of a comment to provide a tutorial on
the language (unless you're actually writing a tutorial program).
Rather, a comment should illuminate the *logic* of the activity by
either amplifying, clarifying, or otherwise providing a rationale' for
the code in question. Demanding that programmers provide comments
about the syntax and semantics of the language is - to me - absurd.
For example, some time ago, I was doing some programming with embedded
PIC-based hardware. The comments for that code are intended to
illuminate how the *hardware* was being exploited, not how to use PIC
asm:
...
scan:
incf current_col,F ; pickup next column to scan
movlw MAX_COL+1 ; if current_col > MAX_COL then
subwf current_col,W ; we just did last column, so start over
btfss STATUS,Z ; zero means we need to start over
goto key_scan ; nope, go look for key hits
clrf current_col ; yes, reinit column counter
goto scan
...
The only possible exception to this I can think of is when there is
some non-obvious side-effect (i.e. language and/or hardware is
"misfeatured"):
mov A,B ; Moving A into B also will also arm
; the nuclear warhead if the CPU is
; hotter than 110C
--
----------------------------------------------------------------------------
Tim Daneliuk tun...@tundraware.com
PGP Key: http://www.tundraware.com/PGP/
--
http://mail.python.org/mailman/listinfo/python-list
