Re: Commenting code

["Donald L. Dobbs" <donaldldobbs@home.com>]

"Shmuel (Seymour J.) Metz" wrote:
> 
> In <3B20EDAC.5A4F7BD4@home.com>, on 06/08/2001
>    at 03:22 PM, "Donald L. Dobbs" <donaldldobbs@home.com> said:
> 
> >label: ADC     A,$01
> 
> >This is a perfectly good instruction to do an add with carry to the
> >accumulator A.
> >So what?  But if you add the comment "Increment the shaft encoder
> >counter until limit reached" then I have some idea of what the code
> >is SUPPOSED to be doing and how that snippet of code relates to the
> >overall problem to be solved.
> 
> Nu? In what way does that echo the code? If, instead, you add the
> comment "increment the accumulator with carry", would you defend the
> comment as necessary?
> 
Of course "increment the accumulator with carry" as a comment doesn't
tell me anything more than I can already discern by looking at the code.
The point I'm trying to make is that I am handed some assembly language
code written by someone else in a different country in a different time
zone who is a junior programmer and didn't do a decent job of
documenting his program. He's generally unavailable and uncooperative. 
[This is an actual case.] His code has a bug in it. I have to fix it on
my own. Unless there is some documentation somewhere (preferably near
the code) that tells what the program is SUPPOSED to do and the
rationale of his code as how he implemented a solution, my job really
becomes tough because I have no baseline.  I can look at the code and
see what bit fiddling it actually does. But is that what it is supposed
to be doing?  Properly documented code allows me to get to the heart of
the problem rapidly; otherwise it becomes a big job of reverse
engineering.

> --
> -----------------------------------------------------------
>      Shmuel (Seymour J.) Metz, SysProg and JOAT
>      Atid/2
>      Team OS/2
>      Team PL/I
> 
> Any unsolicited commercial junk E-mail will be subject to legal
> action.  I reserve the right to publicly post or ridicule any
> abusive E-mail.
> 
> I mangled my E-mail address to foil automated spammers; reply to
> domain acm dot org user shmuel to contact me.  Do not reply to
> spamtrap@library.lspace.org
> -----------------------------------------------------------