Messages in this thread | | | Date | Mon, 27 Sep 1999 00:33:26 -0500 (CDT) | From | Oliver Xymoron <> | Subject | Re: [Q]: Linux and real device drivers |
| |
On Sun, 26 Sep 1999, Benjamin Scott wrote:
> 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/
| |