Subject: Re: Management
From: Erik Naggum <erik@naggum.net>
Date: Tue, 17 Jul 2001 08:40:35 GMT
Newsgroups: comp.lang.lisp
Message-ID: <3204348033355156@naggum.net>

* Thomas F. Burdick
> While a fn-by-fn paraphrasing of code is not sufficient documentation, it
> *can* be an important part of documenting a system, if the overall system
> is also described, and the code you're paraphrasing is opaque (this will
> allow someone maintaining the code to find the relevant functions without
> being forced to puzzle through all the code).  It is, of course, of
> questionable value if the code is easy to read.

  I think this should be in the code, very close to the function body,
  possibly _in_ the functionb ody.  Documentation strings in Common Lisp
  should have this purpose and should be well supported.  (We currently
  lack the ability to extract documentation for a system with a few simple
  functions (they are easy to write, though).)  However, taking such "code
  documentation" out of the code is often a recipe for disaster: You soon
  lose the connection between the actual and the documented code.  Both
  comments and documentation strings serve a purpose.  I think it is a good
  idea to comment on things only in close proximity to that commented on.

> Speaking from experience,

  Experience is what you get in the absence of what you wanted or expected.

#:Erik
-- 
  Travel is a meat thing.