Loading ...
Sorry, an error occurred while loading the content.

Agile documents?

Expand Messages
  • kerrykimbrough
    The epistomology thread was nifty, but it departed from the issue that seems more crucial: Are (test) documents useful or a waste of time? When is a document a
    Message 1 of 155 , Dec 4, 2003
    • 0 Attachment
      The epistomology thread was nifty, but it departed from the issue
      that seems more crucial: Are (test) documents useful or a waste of
      time? When is a document a better "transport" than a conversation?
      Never? Sometimes?

      The XP hard line -- avoid documents, just talk -- is what I think
      I'm hearing from Ron.

      For me, this is an area where XP has overreacted. I definitely see a
      place for (non-code) documents in an agile process. The essential
      work of a sw development project is building knowledge, plus sharing
      and distributing the knowledge effectively among all of the people
      involved. (Subsequent to this, the application of that knowledge by
      any individual is *relatively* straight-forward.) Documents work
      because you can use them early (models that build knowledge),
      because they persist (you're not crippled by your imperfect memory),
      because they're efficient (you don't have to keep repeating the same
      conversation with perfect fidelity), because they can capture
      details (not just vague impressions), because they can be reviewed,
      critiqued, and corrected (unlike your trembling thoughts), because
      they remain (unlike you, you job-hopper!), etc.

      I don't deny the real peril of over-documentation, which is why an
      agile project ought to insist that all documents are purposeful,
      i.e. contribute to the knowledge construction. Neither do I deny the
      value of conversation in a small team nor do I claim that all
      knowledge can or should be captured in a document.

      ---
      Regards,
      Kerry
    • kerrykimbrough
      I agree it s time for this thread to end. I ll close out my contribution with some final comments here. To Bret, who wanted an example of a requirement that
      Message 155 of 155 , Dec 19, 2003
      • 0 Attachment
        I agree it's time for this thread to end. I'll close out my
        contribution with some final comments here.

        To Bret, who wanted an example of a requirement that needs an
        enormous number of examples to completely express the code/tests to
        be done, I refer to post #2896. (Another example from the aviation
        business -- it's bizarre how often that domain has come up here.
        Next time, you hold the giraffe.)

        In arguing for the importance of specs, I have been feeling my way
        around a concept I've called "Contract-Driven Development". To
        Brian, who wanted an example of how CDD works, I refer to post
        #2962. To be more concrete, at a detailed level (say, provoking a
        new method), it would go something like this.

        0. Consider what you intend the method to do.

        1. Write the method signature, with Javadoc describing your
        complete intentions. This is the contract. You want to know and
        express your intentions as clearly and completely as you can, but
        you expect that there might be some mistakes. You will cope with
        this by iterating of this and succeeding steps as needed.

        2. Confident the contract is right? If not, get some buddies to
        review it and rework if necessary.

        3. Based on the contract, write a test case.

        4. Write the code that makes this test case pass.

        5. Repeat #2-4 until you're satisfied the method code is complete
        and correct. Notice that you could do #3 and #4 in any order or even
        simultaneously.

        I feel that CDD can be just as agile as TDD. In fact, it's almost
        exactly the same, except for the addition of #1-2. But what a
        difference this makes! First, you end up with tests, code, and
        contract. For others that come later, after all traces of your
        current conversations have vanished, only the contract expresses
        what you *intended* and therefore what they can or must do next.
        Also, because the contract is real not tacit, you have a good chance
        of finding and fixing defects sooner and cheaper. Also, a real (not
        tacit) contract can be shared more reliably over time and space,
        making it possible to create tests and code in parallel, with lower
        communication cost and less backtracking.

        I work exactly like this. Probably some of you do, too. I know it
        works. But your experience may be different, so to progress we have
        to look deeper, for principles plausible enough to try out on our
        next experience.

        For example, I think CDD also makes sense at a higher level of
        abstraction (say, when you're about to create a new class, or a new
        set of collaborating classes, or a new UI screen, etc.) But here it
        becomes less clear exactly which representations of the "contract"
        can be both effective and agile. I don't have all the answers for
        that, and I was hoping to learn more about it here, but so far I
        haven't. (I know about FIT, but it suffers from the acknowledged
        limitations of spec-by-example.)

        --
        Regards,
        Kerry
      Your message has been successfully submitted and would be delivered to recipients shortly.