Docstrings considered too complicated

[Mark Lawrence]

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.

 

[Steven D'Aprano]

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.

 

[John Bokma]

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.

 

[MRAB]

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!

 

[Alf P. Steinbach]

* MRAB:

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

 

[Steven D'Aprano]

Eh? It's a bad comment, it's of the same quality as:


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.

 

[MRAB]

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...". ;-)

 

[Tim Daneliuk]

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

 

[D'Arcy J.M. Cain]

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.

 

[Steven D'Aprano]

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_ugn_unw/Basic-Assembler-Syntax.html

 

[Steven D'Aprano]

Ah, yes, "apparently". That's like saying "someone down the pub told
me...". ;-)

Not down the pub, somebody on Usenet. Are you trying to suggest that
people might propagate falsehoods on the Internet???

 

[Steven D'Aprano]

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

I had an embedded device that did *just that*, but only on Tuesdays.

 

[John Pinner]

Hi all,

a company that works with my company writes a lot of of their code in
Python (lucky jerks). I've seen their code and it basically looks like
this:

"""Function that does stuff"""
def doStuff():
    while not wise(up):
        yield scorn

Now my question is this: How do I kill these people without the
authorities thinking they didn't deserve it?

A good way to control Python contractors is (given that firstly there
are functional specifications to comply with, and tests to pass) is to
impose the following condition:

that all code delivered must reach a score of (say) 9.5 or more when
checked by pylint

and pylint could be the way to demonstrate the problems to the
'authorities'.

If payment depends on such a measure, things will change quite
quickly.
John
--

 

[John Bokma]

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.

It doesn't matter. Both your comments are wrong from my point of
view. Someone who doesn't know in which direction the move happens is
certainly not qualified to modify the code. And as for learning, he/she
should start with a book, not with a piece of code that requires a
comment on every line unless one can guess its meaning.

 

[Andreas Waldenburger]

A good way to control Python contractors is (given that firstly there
are functional specifications to comply with, and tests to pass) is to
impose the following condition:

that all code delivered must reach a score of (say) 9.5 or more when
checked by pylint

Now that *is* a good idea. I hadn't thought about that.

But as I said: a) I am (we are) not in a position to impose this (We
don't work with the code, we just run the software). And
b) I wasn't quite serious with this anyway.

But still, I'll keep that in mind.
/W

 

[Gregory Ewing]

You could think of it as a not bad use of the design principle "Clear The
Simple Stuff Out Of The Way First". Destinations are commonly a lot simpler
than sources

That's not usually true in assembly languages, though,
where the source and destination are both very restricted
and often about the same complexity.

That's not to say that right-to-left is the wrong way
to do it in an assembly language, but there are less
misleading words than "move" that could be used.

Z80 assembly language uses "load", which makes things
considerably clearer:

LD A, B ; load A with B

 

[MRAB]

That's not usually true in assembly languages, though,
where the source and destination are both very restricted
and often about the same complexity.

That's not to say that right-to-left is the wrong way
to do it in an assembly language, but there are less
misleading words than "move" that could be used.

Z80 assembly language uses "load", which makes things
considerably clearer:

LD A, B ; load A with B

Some processors distinguish between "load" (memory to register) and
"store" (register to memory), and the destination and LHS operand of
binary operations might be the same register, for example:

CLC ; clear the carry
LDA first ; accumulator := byte at first
ADCA second ; accumulator := accumulator + byte at second + carry
STA result ; byte at third := accumulator

 

[Mel]

Calculations for immediate values could be just about anything.

Mel.

 

[Aahz]

I had an embedded device that did *just that*, but only on Tuesdays.

Thus explaining why some people never can get the hang of Tuesdays.
--
Aahz ([email protected]) <*> http://www.pythoncraft.com/

"Many customs in this life persist because they ease friction and promote
productivity as a result of universal agreement, and whether they are
precisely the optimal choices is much less important." --Henry Spencer

 

[Jean-Michel Pichavant]

Some processors distinguish between "load" (memory to register) and
"store" (register to memory), and the destination and LHS operand of
binary operations might be the same register, for example:

CLC ; clear the carry
LDA first ; accumulator := byte at first
ADCA second ; accumulator := accumulator + byte at second + carry
STA result ; byte at third := accumulator

Guys, you sound like people arguing about old school TV show / series
like star treck
- "He was wearing a blue suit !"
- "Check episode number 29, he appeared with a pink one!"

I'm glad I'm too young to had to code in assembler, or to bear the
vision of those unlikely space suits from the 70's ;-)

JM