Erlang language issues

[Richard Carlsson]

On Mon, 22 Apr 2002, Sean Hinde wrote:

> Or on a bad day, when the comments are way out of date, quite
> possibly lead you right up the garden path.
> 
> I guess my point was the rather tired old one that if you understand the
> problem domain, and choose meaningful function names then it should be
> pretty self evident what the program does.

I agree; in as much as possible, the function and module names should
give you most of the clues you need, and comments should neither
duplicate nor be instead of good naming and structuring conventions.

> Maybe it's of most use for library writers where the API docs can be
> kept with the code

Quite so. There are at least two kinds of documentation:

First, we have the comments in the source code (and any other external
documents) which help the programmer understand what the program
actually does, and what the original author was thinking (often: what
the programmer himself was thinking six months ago).

Second, we have the API documentation: How is the program/module/library
used? What functions are there? What arguments do I pass them? What
guarantees are there? What happens if ...? It's very nice indeed to be
able to browse this kind of stuff online, with lots of cross-references.
And it *needs* to be up-to-date.

"Literary programming" usually targets the first, or both, of these, but
is generally overkill unless you plan to publish something like The
TeXbook. Programs like Javadoc or EDoc only target the second category,
making it easy to keep the API documentation updated. However, things
like obsolete docs should be avoided: first of all, use good naming
conventions and you won't have to write so much extra documentation on
the side.

	/Richard


Richard Carlsson (richardc@REDACTED)   (This space intentionally left blank.)
E-mail: Richard.Carlsson@REDACTED	WWW: http://www.csd.uu.se/~richardc/
 "Having users is like optimization: the wise course is to delay it."
   -- Paul Graham