> 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.
Agreed, as I remarked in the bottom of the message you're replying to but
conveniently ignored in your reply. The initial suggestion that started
this thread was to write manpage-like documentation for kernel internals.
This capital-D formalized Documentation is what I'm objecting to. It's
evil.
> > - 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.
Actually, _most_ programmers in the real world don't know how to write
decent code and they instead write lots of design documents and insist on
tons of meaningless comments. They'll write classes to encapsulate a for
loop so it can be made reusable and complain when you don't use their
class library. In fact, lots of companies have crap like this enshrined in
their "code quality" guidelines. Thou shalt put function documentation in
front of every function, thou shalt use silly Hungarian notation, thou
shalt write a design document more tedious than the actual coding before
you've even started, thou shalt make everything a giant switch statement,
thou shalt think ActiveX is clever. Fortunately, these people rarely try
to hack kernel code due to the lack of documentation.
> > - and there are more important/interesting things to do
>
> Interesting, possibly. Important? Well.... look at Windows. Was testing
> less important then coding?
Maybe. But they sure as hell wrote a lot of Documentation. Many CDROMs
worth. You can be sure they did tons internally as well - probably for all
their DLL entry points.
-- "Love the dolphins," she advised him. "Write by W.A.S.T.E.."
- 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/