Language for the ages

[David Cantrell]

On Fri, Oct 14, 2005 at 09:40:52PM -0700, Chuck Guzis wrote:

> I start grinding my teeth when I read stuff like this:
> 
> 	PSHR	R2			;  Push R2 onto the stack
> 	MVII		10,R1			;  Move 10 to R1
> 
> A comment on every line that describes exactly what's happening without any
> sort "big picture".  Absolutely meaningless.

Grargh!  When I wrote our coding guidelines at work, I made it very
clear that comments shuold describe the algorithm, not just each line of
code.  So, for example, instead of "Push R2 onto the stack" it would say
"squirrel R2 away because it's gonna get clobbered in a minute and we'll
need it again", followed later by "retrieve the value we saved earlier,
so that now we can ...".

-- 
David Cantrell | Reality Engineer, Ministry of Information

     Gehyrst þu, sælida, hwæt þis folc segeð?
     Hi willað eow to gafole garas syllan,
     ættrynne ord and ealde swurd,
     þa heregeatu þe eow æt hilde ne deah.
                -- Byrhtnoð