Date: Sun, 12 Aug 2001 19:51:05 -0700 From: Joe Kelsey <joe@zircon.seattle.wa.us> To: current@freebsd.org Subject: Documentation in FreeBSD Message-ID: <15223.16537.621443.350921@zircon.zircon.seattle.wa.us>
next in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?15223.16537.621443.350921>