Re: Squid NTLM authentication

On Sat, Apr 15, 2000, Henrik Nordstrom wrote:

> Hmm.. I have been thinking about how we could make the programmers guide
> a more natural part of the development. One idea I have is to split the
> guide source up and put it in the relevant source files instead of
> separately, and have a small pre-processor which collects the fragments
> together and builds the book from it. This should make it easier to
> remember to write/update the documentation while hacking as it gets more
> visible to the "hacker". Any comments?

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

IIRC, there was a study that examined the staleness/appropriateness of
the "for-manual" in-code comments in large projects compared to
stand-alone programming manuals. They found no significant improvement
from using the former approach and speculated that programmers tend not
to update comments if the comments are longer than a few lines.
Moreover, some believe that programming productivity decreases as the
distance between related code blocks increases.

I do not trust SE and SE studies much but tend to agree with the
conclusions above.

$0.02,

Alex.
Received on Sat Apr 15 2000 - 12:03:36 MDT