lkml.org 
[lkml]   [1999]   [Sep]   [27]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    /
    Date
    From
    SubjectRe: [Q]: Linux and real device drivers
    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/

    \
     
     \ /
      Last update: 2005-03-22 13:54    [from the cache]
    ©2003-2014 Jasper Spaans. hosted at Digital Ocean