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
    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/

    \
     
     \ /
      Last update: 2005-03-22 13:54    [W:0.023 / U:91.876 seconds]
    ©2003-2016 Jasper Spaans. hosted at Digital OceanAdvertise on this site