I once worked with a group of ex-IBM assembler jocks.  They had a very
strict rule requiring 2 comments for every 3 lines of assembler code.

One of these guys was a  poetry buff.  The right-hand column of his listings
had neat lines of iambic pentameter.  The poetry had nothing to do with the
source code, but it was always passed by the official code-checkers.  BTW --
he was a fantastic coder and produced lots of good code in spite of all the
time he spent writing (bad) poetry on company time.

Trying to achieve good code by having simple-minded rules not only doesn't
work, but positively invites rebellious behavior from the best programmers.
It'll never turn the bad programmers into good ones, but it'll piss off the
good ones every time.

> -----Original Message-----
> From: Wagner Lipnharski [SMTP:wagnerl@EARTHLINK.NET]
> Sent: Monday, November 15, 1999 9:42 AM
> To:   PICLIST@MITVMA.MIT.EDU
> Subject:      Re: C vs. ASM
>
> > >When done in assembler it is
> > >- undocumentable
> > >- dangerous
> > >- may stop working at any time if you don't remember you did it and
> > >- you should instantly fire the programmer who does it if he / she ever
> > does
>  [snip]
>
> Well, I think here we need to say that a software professional, a good
> one, one that deserve this title, much before to be a software writer,
> should be a "documenter".
>
> I would dare to say that, the professionalism start by the details, and
> in software, want you to agree or not, good comments in a source is not
> only a must, it is imperative.
>
> After I started to comment each single line of the assembler source, I
> noticed a reduction in errors and problems, because commenting a source
> is also a way to interface a machine language code to our human mind
> language.
>
> If you don't believe me, try to write two lines of not commented code
> and get it ISO-9000 approved,
>
> Probably you can find lots of software genius around that hate
> commenting his/her software, ok, this is the way they do it, but it is
> at least irresponsible.  It is the same as giving birth to a baby and
> not identifying he/she with an Identification hospital tag... would you
> be able to recognize the baby next day in middle of other 50 babies?
>
> Probably the best way to get it done, is discount from the software
> professional's monthly payment a proportional quantity in money, of the
> non commented source code lines... then they will start to do it right
> immediately.  You should remember that if you are the boss, or the
> company's owner, you decide how the work should be done, and (I am sorry
> to say this) if you are not achieving this goal, it is only *your*
> fault, nobody else should be held responsible.