From ... Path: archiver1.google.com!newsfeed.google.com!newsfeed.stanford.edu!news.tele.dk!134.222.94.5!npeer.kpnqwest.net!nreader1.kpnqwest.net.POSTED!not-for-mail Newsgroups: comp.lang.lisp Subject: Re: Management References: <3B50CF80.61A23F52@yahoo.com> <3b519e68.380137109@news.blueyonder.co.uk> <3B529D71.330337B0@yahoo.com> Mail-Copies-To: never From: Erik Naggum Message-ID: <3204348033355156@naggum.net> Organization: Naggum Software, Oslo, Norway Lines: 25 User-Agent: Gnus/5.0808 (Gnus v5.8.8) Emacs/20.7 MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Date: Tue, 17 Jul 2001 08:40:35 GMT X-Complaints-To: newsmaster@Norway.EU.net X-Trace: nreader1.kpnqwest.net 995359235 193.71.66.1 (Tue, 17 Jul 2001 10:40:35 MET DST) NNTP-Posting-Date: Tue, 17 Jul 2001 10:40:35 MET DST Xref: archiver1.google.com comp.lang.lisp:13227 * 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.