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.