Re: succinctness = power

[Dan Weinreb <address@hidden>]

   Date: Fri, 31 May 2002 11:12:12 -0400
   From: Ken Anderson <kanderson@bbn.com>

   Kent Beck says that no more than 1% of the lines of code he writes is 
   documentation.  He does work hard at making the code he writes clear.

Unfortunately, I find there are often things that I, as the writer,
want to express to the (future) reader of the code, which are not
sayable in the programming language.

Here are a few from our code base:


    // NOTE: For each call to SomeFactory.init() in this method, there must
    // be a corresponding call to SomeFactory.destroy() in
    // Node.destroyAll(). Factories must be destroyed in reverse of the
    // order they were initialized.



    } else {
      // Send a message to the PFE that does handle this PRN.
      // It is important that the resume happens in the right PFE, since timers
      // only work if they are started and stopped by the right PRN for the
      // instance.  
      sendSignalToProcess(pid, RESUME_PROCESS);
    }



    // Do this even if instances.xml exists, just to prevent all-instances from
    // getting out of synch.
    addPRNToAllInstancesDoc(prn);
    return doc.getDOMDocumentNode();


        if (newPid) {
          // handleEvent filled in the collaboration use.  So that this
          // case returns the same kinds of collaborations as the case
          // where the message is enqueued, we null it out before returning.
          event.to().correlation().setCollaborationUse(null);
        }

I don't think that these could have been avoided by "writing the code
more clearly".  For example, some are making statements about global
properties that don't correspond to any one line of code.  Would it be
better to write these in some kind of formal language that could be
machine-interpreted for various assorted nice benefits?  Well, I'd be
interested in checking out a proposed tool/language of that sort...

-- Dan