Subject: Re: business case for mechanized documentation
From: "Stephen J. Turnbull" <>
Date: Thu, 13 Apr 2006 09:48:18 +0900

>>>>> "Kelly" == Kelly Anderson <> writes:

    Kelly> If your code MUST describe itself, then you have an
    Kelly> incentive to write clear code that can be easily read by
    Kelly> others.

I gather you haven't read _Obfuscated C_!

    Kelly> It's possible, but why would you need to if the code were
    Kelly> readable?

Static point of view: it's often the case that important information
is very local in application.  Take

int HashTableSize = 13;  /* should be prime */

You *don't* want this:

    for (i = 0; i < HashTableSizeWhichShouldBePrime; i++)

Dynamic point of view: there's very little code which can't be made
*more* readable.  Especially if you're maintaining a legacy
application, like XEmacs.  Also, maybe it would help if we think of
Rich's project as a very-high-level code browser, rather than a
documentation generator---comments are just one aspect.  (In this
context; of course it is also a documentation generator.  But once you
get dynamic, you can choose which point of view is more useful to you
at run time!)

Graduate School of Systems and Information Engineering   University of Tsukuba        Tennodai 1-1-1 Tsukuba 305-8573 JAPAN
        Economics of Information Communication and Computation Systems
          Experimental Economics, Microeconomic Theory, Game Theory