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

>>>>> "Kelly" == Kelly Anderson <KAnderson@dentrix.com> 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
http://turnbull.sk.tsukuba.ac.jp/        Tennodai 1-1-1 Tsukuba 305-8573 JAPAN
        Economics of Information Communication and Computation Systems
          Experimental Economics, Microeconomic Theory, Game Theory