code comments (was Re: Scheme function to print out active Voice context during interpretation?)

[demery]

On Mon, Dec 15, 2008, Francisco Vila <address@hidden> said:

> I have a question for the few developers that in some degree do
> understand the source code and are able to hack it, fix bugs,
> implement new features, etc.
> 
> Is the code properly commented, so that (thinking on the future) new
> people can learn from it without having to figure out all the time
> what does each function, file etc. do? 

Newbie to the project, but one who has been programming since 1968, this
is something I have discussed at length with other experience programmers.
 I speak in general, have yet to delve into Lp code at all, so please
forgive if this is already covered by a project policy or perhaps a gnu
policy.

Good code commenting is a challenging skill, at its best the comments on
archived code should

  Be accurate, uptodate, not telling lies.
  Explain why someone would want to invoke the code
  Describe context for use - arguments in, side effects, value(s)
returned.
  Cite sources for non-trivial algorythms used, if original, publish a
white paper to the project which can be cited.

In many cases comments will exceed the code itself.
Line-by-line comments are sometimes useful but should give information
beyond the obvious.  In a language like postscript the expected state of
the stack is ofen a useful comment.

Some projects embed text for documentation and help files with the code
itself to encourage parallel maintenance.
-- 
Dana Emery