Velocity Reviews - Computer Hardware Reviews

Velocity Reviews > Newsgroups > Programming > Python > Docstrings considered too complicated

Reply
Thread Tools

Docstrings considered too complicated

 
 
Mark Lawrence
Guest
Posts: n/a
 
      02-26-2010
Jean-Michel Pichavant wrote:
> Andreas Waldenburger wrote:
>> On Fri, 26 Feb 2010 09:09:36 -0600 Tim Daneliuk <(E-Mail Removed)>
>> wrote:
>>
>>
>>> On 2/24/2010 2:23 PM, Andreas Waldenburger wrote:
>>>
>>>> [stuff]
>>>>
>>> Reminiscent of:
>>>
>>> mov AX,BX ; Move the contents of BX into AX
>>>
>>>

>> Well, there might be some confusion there as to what gets moved where,
>> wouldn't you say? I guess this goes away after a couple of months,
>> though.
>>

>
> I agree to that statement, I was surprised that mov AX,BX assumes that
> BX is the source, and AX the destination. I never programmed in
> assembler though.
>
> JM


The obvious solution to this problem is to write the assembler code in
your own way, and then use Python to change the code to the appropriate
target. Any of the solutions listed here would presumably suffice.
http://nedbatchelder.com/text/python-parsers.html

Regards.

Mark Lawrence.

 
Reply With Quote
 
 
 
 
Steven D'Aprano
Guest
Posts: n/a
 
      02-27-2010
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.


> And, yes, I've actually seen that as well as:
>
> ; This is a comment


Which might be a good comment, if it were part of an unfamiliar file
format where the reader were not expected to know what is a comment and
what is significant. For instance, I've seen similar comments at the top
of config files.


However, I'm pretty sure that a comment like this is inexcusable:


x = x + 1 # Add one to x.



--
Steven
 
Reply With Quote
 
 
 
 
John Bokma
Guest
Posts: n/a
 
      02-27-2010
Steven D'Aprano <(E-Mail Removed)> 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.

--
John Bokma j3b

Hacking & Hiking in Mexico - http://johnbokma.com/
http://castleamber.com/ - Perl & Python Development
 
Reply With Quote
 
MRAB
Guest
Posts: n/a
 
      02-27-2010
Steven D'Aprano wrote:
> 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.
>

[snip]
If you're reading and/or writing at assembly language level then you
should know what it does anyway!

The assembly languages of virtually all the processors that I've come
across put the destination first, eg. x86:

SUB AX,BX
MOV AX,BX

which does:

AX := AX - BX
AX := BX

and ARM:

SUB R0,R1,R2
MOV R0,R1

which does:

R0 := R1 - R2
R0 := R1

The only assembly language I know of which does it the other way round
is 68x00:

SUB D0,D1
MOVE D0,D1

which does:

D1 := D1 - D0
D1 := D0

I know which I prefer!
 
Reply With Quote
 
Alf P. Steinbach
Guest
Posts: n/a
 
      02-27-2010
* MRAB:
> Steven D'Aprano wrote:
>> 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.
>>

> [snip]
> If you're reading and/or writing at assembly language level then you
> should know what it does anyway!
>
> The assembly languages of virtually all the processors that I've come
> across put the destination first, eg. x86:
>
> SUB AX,BX
> MOV AX,BX
>
> which does:
>
> AX := AX - BX
> AX := BX
>


A bit off-topic, but there are /two/ main syntaxes for x86 assembly, namely
Intel syntax (the above syntax, used by MASM, old TASM etc.) and AT&T syntax.


<example>
C:\test> echo int main(){ int x = 42; } >blah.cpp

C:\test> g++ blah.cpp -S -masm=intel

C:\test> type blah.s | find "42"
mov DWORD PTR [ebp-4], 42

C:\test> g++ blah.cpp -S -masm=att

C:\test> type blah.s | find "42"
movl $42, -4(%ebp)

C:\test> _
</example>


Personally I find the AT&T syntax very hard to read.

All those percent signs hurt my eyes...




> and ARM:
>
> SUB R0,R1,R2
> MOV R0,R1
>
> which does:
>
> R0 := R1 - R2
> R0 := R1
>
> The only assembly language I know of which does it the other way round
> is 68x00:
>
> SUB D0,D1
> MOVE D0,D1
>
> which does:
>
> D1 := D1 - D0
> D1 := D0
>
> I know which I prefer!


Cheers,

- Alf
 
Reply With Quote
 
Steven D'Aprano
Guest
Posts: n/a
 
      02-27-2010
On Fri, 26 Feb 2010 18:47:26 -0600, John Bokma wrote:

> Steven D'Aprano <(E-Mail Removed)> 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
 
Reply With Quote
 
MRAB
Guest
Posts: n/a
 
      02-27-2010
Steven D'Aprano wrote:
> On Fri, 26 Feb 2010 18:47:26 -0600, John Bokma wrote:
>
>> Steven D'Aprano <(E-Mail Removed)> 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...".
 
Reply With Quote
 
Tim Daneliuk
Guest
Posts: n/a
 
      02-27-2010
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 <(E-Mail Removed)> 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 http://www.velocityreviews.com/forums/(E-Mail Removed)
PGP Key: http://www.tundraware.com/PGP/

 
Reply With Quote
 
D'Arcy J.M. Cain
Guest
Posts: n/a
 
      02-27-2010
On 27 Feb 2010 00:02:40 GMT
Steven D'Aprano <(E-Mail Removed)> wrote:
> On Fri, 26 Feb 2010 09:09:36 -0600, Tim Daneliuk wrote:
> > 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.


But it isn't English, it's assembler. If someone doesn't know that
assembler they have no business trying to work in it.

A good comment would be "move number of sheep into accumulator" or
something equally as descriptive. A person who knows the assembler
knows that the BX register will be copied (not "moved" btw) into the AX
register. What they want from the comment is some idea why.

Yes, understanding assembler is hard. You aren't going to learn it
from the comments.

--
D'Arcy J.M. Cain <(E-Mail Removed)> | Democracy is three wolves
http://www.druid.net/darcy/ | and a sheep voting on
+1 416 425 1212 (DoD#0082) (eNTP) | what's for dinner.
 
Reply With Quote
 
Steven D'Aprano
Guest
Posts: n/a
 
      02-27-2010
On Sat, 27 Feb 2010 00:54:53 +0000, MRAB wrote:

> The assembly languages of virtually all the processors that I've come
> across put the destination first, eg. x86:


Incorrect. x86 assembly has two distinct syntax branches, "Intel
syntax" (which is most common in the Windows world according to
Wikipedia) and "AT&T syntax".

See for example:

http://gcc.gnu.org/onlinedocs/gnat_u...er-Syntax.html


--
Steven
 
Reply With Quote
 
 
 
Reply

Thread Tools

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is On
HTML code is Off
Trackbacks are On
Pingbacks are On
Refbacks are Off


Similar Threads
Thread Thread Starter Forum Replies Last Post
Re: Docstrings considered too complicated mk Python 2 03-03-2010 11:16 PM
Re: CSS2 Way Too Complicated Mark Parnell HTML 1 07-17-2004 09:24 AM
Re: CSS2 Way Too Complicated Mark Parnell HTML 0 07-16-2004 11:21 PM
CSS2 Way Too Complicated Davmagic .Com HTML 27 07-16-2004 04:24 PM
Re: CSS2 Way Too Complicated Smidak HTML 11 07-16-2004 01:39 PM



Advertisments