Code as documentation: was Re: [agile-usability] Where the BA Ends ...
- (responding to Alex)
design. If>> Well actually - I would say that :-) The code embodies the
>> the code isn't clear enough for a developer tofigure out the design
>> from the code the code needs to bewritten more clearly.
>with this one. :) Code
> Oh my, I'm not even sure where to begin
long> does in no way document anything ; it's a result from a
goals,> process of give and take, and speaks nothing of ideas,> intentions, models and so forth.Hmm... maybe you'd have a different opinion if you kept thedesign simple, but I guess you will have to try it for yourselffor a while.I find that the unit tests give the low level goals, the useracceptance tests give the high level goals. With good separationof concerns, the intentions are clear at the architecturallevel because architectural code is separated out. I mightwant to keep a (business) domain model and a high levelarchitectural model explicitly. I might want some similarhigh level model of the UI that gives me a quick overview ofthe key ideas that underpin the detail.You have to produce the code anyway; it makes sense toget it to do as good a job as reasonably possible ofdocumenting itself.
> The code does not embody the design; thecode is a> functional appropriation of someones ideas of what the> design is all about.Of course the code embodies the design decisions thatwere made. What it doesn't do is document the alternativedecisions that were rejected, or why they were rejected.Sometimes the reasons were quite arbitrary and the decisionwent a particular way just because a decision had to bemade. Later requirements may lead to the decision nowgoing the other way. So, make the change, Don't sweat it.If you had a really good reason for going one way ratherthan the other, try and put in a test that demonstrates theproblem you are avoiding by going that way.And really, there's no problem with adding a comment to thecode saying "We went this way here because...".Paul Oldfield
- 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?
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.