lkml.org 
[lkml]   [2003]   [Apr]   [17]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    /
    Date
    From
    SubjectRe: kernel support for non-English user messages
    On Tue, Apr 15, 2003 at 11:02:15AM -0700, Eric Altendorf wrote:
    > If you find yourself having to write comments and documentation to
    > explain your code, probably your identifiers are not well named, your
    > functions are not short enough, and your code is not well structured
    > enough.
    >
    > Ideal code is completely self-documenting.

    That's true if documentation serves only to describe _what_ the
    code does. You've ignored the need to describe _why_ the code
    was written in this way. For example, documentation can note some
    feature of the hardware which requires special handling, or it can
    describe some emergent property which isn't obvious even if all
    the code is understood.

    That's why local comments should explain non-obvious trickery used,
    perhaps the exploitation of a poorly documented side-effect of some
    instruction, and block comments or external documentation should
    help the reader understand why things are done some particular way.
    For instance, if the code implements some specific, well documented
    algorithm, it should reference the algorithm by name.

    --
    Randolph Bentson
    bentson@holmsjoen.com
    -
    To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
    the body of a message to majordomo@vger.kernel.org
    More majordomo info at http://vger.kernel.org/majordomo-info.html
    Please read the FAQ at http://www.tux.org/lkml/

    \
     
     \ /
      Last update: 2005-03-22 13:34    [W:4.057 / U:0.772 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site