Re: [Q]: Linux and real device drivers
Wade Hampton (whampton@staffnet.com)
Mon, 27 Sep 1999 09:54:16 -0400
Oliver Xymoron wrote:
>
> 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.
Maybe, maybe not..... A formal style would make it much easier to
extract docs for others that just want to use the API.
>
> > > - 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.
Programmers, like all others, come in many skill levels. For most
corporations that want code to run for years, they have to have adequate
documentation including module and function headers. Adding a header
in front of functions (unless a bunch of single line functions), is a
good practice for maintenance. Remember my iceburg analogy....
As for hungarian notation -- I have found that code I write using it
is easier to maintain as the type of variables is clearly in the
variable name. Once, when using PLM on an 8031, we had a strange bug
that we traced to a timer using a char variable, but the valid range
was something like 300 or so -- hungarian notation makes finding
such bugs MUCH easier. Just because Microsoft adopted this notation
does not make it evil -- it has its place. It is just another style,
but it is better suited to applications code, not kernel code
>
> > > - 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.
They are a large corporation with many paid programmers of multiple
skill levels. They have to maintain code written years ago (or, at
least
are supposed to, but they kill off their old products like Win32S).
There is a place for docs. There is a place for interface specs.
Cheers,
--
W. Wade, Hampton <whampton@staffnet.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/