On 27 Sep 2000 15:10:25 +0200
 Ketil Malde <[EMAIL PROTECTED]> wrote:
> [stuff deleted]
> 
> Anyway, my problem with literate programming is that I
> don't really
> know what to put in there with the source code.  Usage
> documentation?
> Explanations about implementation details?  Tutorial and
> examples?
> 
> I guess one reason the Perl documentation works so well,
> is that the
> target is clearly defined: man pages.

As your Perl example illustrates, it probably depends on which language you are 
commenting for.  For example, when I was using JavaDoc for Java, I would comment each 
method, and put the following in each comment:

  * the purpose of the method (what it's used for)
  * the type of the method (in Java, this meant its return value type, "void" if null)
  * the argument(s), if any, to the method
  * the usage of the method
  * if the underlying algorithm was not immediately obvious, an explanation of how the 
method worked, so that it could be easily modified and reused

Since Haskell's types (including the argument(s), which are part of the types in 
Haskell) tend to be self-documenting, the type and the argument(s) above should both 
probably be omitted.  However, the remaining ones above still seem to be possible 
candidates for what to put in the comments.

I would appreciate any other input on this.  My goals for the comments are to focus on 
the following issues:

  * simplicity (obfuscated code tends to be difficult to comment)
  * clarity
  * correctness (since explaining the code forces me to analyze it carefully, the 
process also tends to reduce bugs)
  * reusability (explaining how the code works tends to make it easier to modify, and 
hence more reusable)

Allow me to add that an additional goal for my programming in general is the following:

  * portability (since the goal is to create write-once, run-many programs)

Benjamin L. Russell
[EMAIL PROTECTED]
[EMAIL PROTECTED]
"Furuike ya!  Kawazu tobikomu mizu no oto."  --Matsuo Basho

Reply via email to