Re: [OT?] Coding Style

[Gregory Maxwell]

On Mon, Jan 22, 2001 at 11:04:50AM -0500, Jonathan Earle wrote:
> WRONG!!!
> 
> Not documenting your code is not a sign of good coding, but rather shows
> arrogance, laziness and contempt for "those who would dare tamper with your
> code after you've written it".  Document and comment your code thoroughly.
> Do it as you go along.  I was also taught to comment nearly every line - as
> part of the coding style used by a large, international company I worked for
> several years ago.  It brings the logic of the programmer into focus and
> makes code maintenance a whole lot easier.  It also helps one to remember
> the logic of your own code when you revisit it a year or more hence.

Not wrong: You should document the interface, and any strange gotchas that
you faced while writing the function (like hardware bugs, etc). Then, if the
next person can't understand the code by reading it:

1. He's not qualified to change it.
*OR*
2. The code is crap, it needs to be rewritten anyways, good interface
documentation makes that possible.

Documenting every detail just encourages people with a paper thin
understanding to go and foul it up in subtile ways, it's better that they be
completely clueless and screw it up obviously.

Good code is simple, clean, and obvious. Sometimes, some code can't be clean
because it's facing a very hard problem, all the more reason to leave it to
gurus.