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?)


To Unsubscribe: send mail to [EMAIL PROTECTED]
with "unsubscribe freebsd-current" in the body of the message

Reply via email to