I would argue, code is a poor substitute for documentation.
> - can never be complete, accurate, or timely enough to match the source
Documentation should not match code line-by-line. See below.
> - <language> is much more ambiguous than C
I have seen *plenty* of ambiguous C code in my not-very-long lifetime! :-)
The fact of the matter is, you can write bad code in any language, be that
language C or English.
I think you have a bad idea of what source-documentation is supposed to do.
Poor documentation explains what the code does. That is bogus: What the
code does should be self-explanatory. If it is not, either the code is bad or
the reader is bad. Either way, something is wrong.
Good documentation gives you an idea of the "brain pattern" in place when
the code was written. The big picture. The design. Maybe why the code does
what it does. Maybe an explanation of what it ties into. A reference to
literature where the algorithm is discussed. Other functions and files to
check out. Common pitfalls. The author's favorite color, if that is needed.
Whatever applies but does not exist in the source code because it cannot by
nature.
Such documentation often takes the form of a README file in a directory,
which gives an overview of what the several files in the directory do, and
points out interesting/important entry-points, functions, data structures,
macros and the like. Or maybe the same thing, applied to a single file and
put at the top of that file.
Yes, you can derive all of this stuff from the code, given time. A lot of
this stuff is not for the person who is already intimately familiar with the
code in question. It is for the guy who has picked up the code for the first
time, and is scratching his head, trying to figure out that big picture. He
will get there eventually, but I like to make his job easier if I can.
> - encourages bad habits
> - developers substitute docs for readable code
First of all, if someone is going to go to the trouble of writing decent
documentation, they will almost always have gone to the trouble of writing
decent code. Second of all, there are existing control mechanisms in place
(Linus ;-) which keep most unreadable code from getting into the kernel.
Just because someone comments their code does not mean those mechanisms are
going to self-destruct.
In fact, it may get better. People may say, "Hey, wait a minute, you're
going about this all wrong!" simply from reading a one-line comment, rather
then reading through two pages of patch and *then* saying, "Hey...".
> - people read the documentation and fear the code
Then those people can not hack the code! :-)
> - when people do read the code, they interpret it as suggested by the
> documentation, missing subtle and not so subtle bugs
Conversely, documentation can make a bug easier to find, because when
comments say one thing and code does another, people start to wonder.
> - fewer people understand the actual code
I would think *more* people would understand the actual code, since now we
have actual code PLUS some explanation of the brain pattern behind it.
Additionally, what if you're implementing X and want to use Y. Should you
have to know every detail about Y just because of X? As someone else said,
what if you just want some memory? Do you have to know every detail about
kmalloc? Or is the calling convention plus the limitations enough?
> - adds more inertia to the interfaces of a system
More code does that, too. :)
> - means changes require a greater investment of effort
Good! Linux is all about investing the effort needed to design and
implement a good system. If someone has to actually put a little thought into
their code, rather then posting the first thing that compiles, maybe Linux
will be even better. :-)
As I am fond of saying, "One man's interface is another man's
implementation."
> - implicitly promises things won't get changed
Do you see a read-only bit on that source file? If not, it is subject to
change. :-)
> - broken designs stay broken longer
Design changes all the time now in Linux, why should we assume documenting
code internals will prevent those changes from happening? Documenting things
may, however, make design flaws more apparent, and/or make updating code to
work with the new design easier.
> - is a lot of work
Good! (See above.)
> - and we've been doing pretty damn well without it
Maybe we can do better, eh? :)
> - and there are more important/interesting things to do
Interesting, possibly. Important? Well.... look at Windows. Was testing
less important then coding?
> - and you don't get very far telling volunteers to do things they don't
> want to
First of all, nobody is suggesting we hire a bunch of kernel police to go
around and beat-up anybody who doesn't comment their code. What has been
suggested is some sort of framework to make documenting the kernel easier, and
then using those docs easier. Frankly, at 60+ megabytes, I think that makes
sense.
Second: If Linus wants to tell volunteers to do things such-and-such a way,
he does. And they do so, or they ship out. This is nothing new.
> - and other people who are motivated in that direction can do it
The suggested ideas would make those people's job easier, while not
impacting the many "all hack, no quack" coders that contribute to Linux.
Just my 1/4 of a byte. ;-)
-- Benjamin Scott dragonhawk@iname.com
- To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to majordomo@vger.rutgers.edu Please read the FAQ at http://www.tux.org/lkml/