seems that this discussion will lead to structural changes in the
networking code. I think it's essential to clean up another deficiency
of the linux networking code: missing or incomplete documentation. IMHO
the whole networking stuff is one the worst documented pieces of code
that I've ever seen.
Don't get me wrong on this: I don't recommend bloating the source with
large amounts of comments. Most of the time it's completely
un-interesting to know about implementation details. But as I see it,
though there are well defined interfaces between the different control
entities, it's really hard to handle them correctly, because it's almost
impossible to find out how they are supposed to be handled. One cannot
expect a driver writer to stick to rules and paradigms if these rules
aren't laid down somewhere. To have a reference implementation of a NIC
driver as a skeleton is OK when it's "coding time". But code is always a
compressed extract of a design idea and having to reconstruct the idea
from the code is error prone, or at least painful. So, "read the code"
is not an appropriate advice most of the time. It slows down development
and increases propability of errors.
A proper interface documentation not only covers data structures,
function calls, there should also be generic information. The reader
should get a "feeling" how his piece of code is supposed to fit into the
whole, without having to find out all the gory details by himself.
Just as a real life example: About to take over the maintenance of the
AX.25 protocol stuff, I tried to find a book or www-reference that
comprehensively covers the network implementation - no go =-| So my
current knowledge of the stuff is a mixture of what I found out by
grep'ing through the sources of the other protocol families, what I know
about operating system design in general, and what I collected by
getting on peoples nerves by asking baby-questions - and trial and
error, of course. And of course by doing this I certainly misinterpreted
several facts.. So it's more difficult for me to say whether or not a
crash/misbehaviuor is due to a bug in my own stuff. That will keep me
busy hunting bugs in bug-free code instead of making real progress. Not
to mention the slowdown in locating and removing bugs in other parts of
the kernel. Don't misread this: Of course I'm able to verify my code up
to a certain extent, trouble starts where my code has to interact with
the rest of the kernel.
Gruss,
Matthias
-
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/