Re: Programmers guide

Alex Rousskov wrote:

> IMHO, such approach makes the code hard to read and modify. I would
> recommend not to write comments longer than a couple of lines.

I did not intend to have the documentation spread out over all the code,
only at the top level (outside any functions), as a prologue to files,
strucures and/or functions.

> Moreover, some believe that programming productivity decreases as the
> distance between related code blocks increases.

That I fully agree on. In-line comments should complement the code and
act as a reminder on why the code looks the way as it does, not document
the code. Code should be mostly self-documenting when you know what the
block as a whole does.

I do beleive that having the documentation in the same file as the code
it talks about helps to remind the programmer to update the
documentation. The programmers who could make the updates rarely read
the programmers-gude documentation separately, but we do read the code.

/Henrik
Received on Sun Apr 16 2000 - 17:09:15 MDT