From owner-freebsd-current Sun Aug 12 19:47:54 2001 Delivered-To: freebsd-current@freebsd.org Received: from zircon.seattle.wa.us (sense-sea-CovadSub-0-228.oz.net [216.39.147.228]) by hub.freebsd.org (Postfix) with SMTP id 7E11F37B40E for ; Sun, 12 Aug 2001 19:47:50 -0700 (PDT) (envelope-from joe@zircon.seattle.wa.us) Received: (qmail 8148 invoked by uid 1001); 13 Aug 2001 02:51:05 -0000 From: Joe Kelsey MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Message-ID: <15223.16537.621443.350921@zircon.zircon.seattle.wa.us> Date: Sun, 12 Aug 2001 19:51:05 -0700 To: current@freebsd.org Subject: Documentation in FreeBSD X-Mailer: VM 6.92 under Emacs 20.7.1 Sender: owner-freebsd-current@FreeBSD.ORG Precedence: bulk List-ID: List-Archive: (Web Archive) List-Help: (List Instructions) List-Subscribe: List-Unsubscribe: X-Loop: FreeBSD.ORG OK, so we have beaten the psm and keyboard code to death. The entire point that I have been trying to make in this discussion is that it is imperative to document design decisions somewhere that is likely to survive changes in maintainer. I have been working as an administrator and programmer for many years. In that time, it has become quite clear to me that the largest effort in any multi-year, multi-person programming effort is documenting what you do in order that those that follow you (or even yourself, several years hence) can figure out what you did and why you did it. The most clever hack that you implement becomes the most obscure, opaque code if you only instrument it with cryptic one-lin comments. I am not speaking against anyone who has put effort into writing and maintaining the excellent code that is FreeBSD. I appreciate the code and all of the effort it represents. However, the constant clamor of the denizens of this list who constantly har "if you don't like it, submit a patch" is extremely annoying. You cannot submit a patch to opaque code without expending massive amounts of effort to figure out the opacity. Please, all I am asking for is that, if there is any long dicsussion about the pros and cons of some design decision, the person responsible for maintaining the code in question should also be responsible for immortalizing the discussion in the code. Either simply copy the most relevant e-mail into a comment or summarize the comments, with, perhaps, a pointer to the e-mail subject line of the discussion to make searching the archives easier on those who follow. What I am pleading for is nothing more than any commercial software house requires of its programmers. Document the design in order that maintainence is easier. Personally, I prefer to use literate programming techniques for this, but that is not possible for many OS functions. Certainly, we could adopt some sort of standard practice to embed design comments in the code. I personally prefer to over-comment as it is hard to determine exactly what someone needs 5 years from now to fix a problem. Of course, illiterate comments can sometimes be worse than no comment, but that is a discussion for another forum. There is a lot of good discussion that goes on on this and other lists that needs to somehow make it into the code or into a separate documentation area (section 4 pages? info docs? articles?) /Joe To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-current" in the body of the message