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

Code as documentation: was Re: [agile-usability] Where the BA Ends ...

Expand Messages
  • PaulOldfield1@aol.com
    (responding to Alex) ... Hmm... maybe you d have a different opinion if you kept the design simple, but I guess you will have to try it for yourself for a
    Message 1 of 76 , Aug 25, 2006
      (responding to Alex)
       
      >>  Well actually - I would say that :-) The code embodies the
      design. If
      >>  the code isn't clear enough for a developer to
      figure out the design
      >>  from the code the code needs to be
      written more clearly.
      >
      > Oh my, I'm not even sure where to begin
      with this one. :) Code
      > does in no way document anything ; it's a result from a
      long
      > process of give and take, and speaks nothing of ideas,
      goals,
      > intentions, models and so forth.
       
      Hmm... maybe you'd have a different opinion if you kept the
      design simple, but I guess you will have to try it for yourself
      for a while.
       
      I find that the unit tests give the low level goals, the user
      acceptance tests give the high level goals.  With good separation
      of concerns, the intentions are clear at the architectural
      level because architectural code is separated out.  I might
      want to keep a (business) domain model and a high level
      architectural model explicitly.  I might want some similar
      high level model of the UI that gives me a quick overview of
      the key ideas that underpin the detail.
       
      You have to produce the code anyway; it makes sense to
      get it to do as good a job as reasonably possible of
      documenting itself.

      > The code does not embody the design; the
      code is a
      > functional appropriation of someones ideas of what the
      > design is all about.
      Of course the code embodies the design decisions that
      were made.  What it doesn't do is document the alternative
      decisions that were rejected, or why they were rejected.
      Sometimes the reasons were quite arbitrary and the decision
      went a particular way just because a decision had to be
      made.  Later requirements may lead to the decision now
      going the other way.  So, make the change,  Don't sweat it.
       
      If you had a really good reason for going one way rather
      than the other, try and put in a test that demonstrates the
      problem you are avoiding by going that way.
       
      And really, there's no problem with adding a comment to the
      code saying "We went this way here because...".
       
      Paul Oldfield
    • Desilets, Alain
      But isn t this turning more and more into a discussion on how we do agile? There s more than one way to do that, and while mine contains a fair amount of
      Message 76 of 76 , Aug 31, 2006
        But isn't this turning more and more into a discussion on how we do
        agile? There's more than one way to do that, and while mine contains a
        fair amount of documentation, yours don't. Right?

        -- Alain:
        Running code over documentation is a basic tenet of Agile.

        So if you put more emphasis on producing documentation than on producing
        working code, then you are not doing Agile.
        ----
      Your message has been successfully submitted and would be delivered to recipients shortly.