--- Richard Baker <[EMAIL PROTECTED]> wrote:
> Jan said:
>
> > Unless requested by a client or an employer, the code illustrates how
> > the finished code works.
>
> The only problem with that is
...We are in complete agreement...I think.
>that the code can only illustrate what it
> actually does rather than what it should do.
Unit Tests, Contracts (if the language has them) Embedid contracts (if you
have the tools). Flat out stated contracts are hypothesis, for which you
havent done the test. They are what you -think- the contract is.
>That's why it's so
> important to have comments
Comments are greate when you can not make the code self documenting. Hoever,
with; discriptive names, embeded information techniques like HN, vertical
alighnment and/or adjoining proofs, it is much much more effective.
>that give the intention of the code,
Yes intention is what you are trying to convey. And so it is all you need to
convey. Anything more and the documentation will allwys turn out to be an
elaborate maze with subtle but significant lies.
> collections of test cases with expected results and other types of
> documentation.
Hu-RA! but not bulks of paper no one looks at becouse it took so long to
update it that some updates were missed and it's chock full of lies.
> It's *very* important that the complete set of this
> stuff should be as clear as possible, because most of the programming
> effort on most projects is in the maintenance phase
Exactly.
>, and in many cases
> the maintenance programmers will be people other than the ones who
> worked on the initial implementation,
Unless of course you just start the project as if it were already in
maintenece.....
> and the initial developers might
> not even be available for consultation.
Strange how the suspects allways seem to disaper.
> Speaking as someone who had to fix many bugs in a ten thousand line
> system with very little documentation and especially poor variable
> naming conventions, learning what code does from the code itself can
> often be quite hard.
So Rich, don't blame a lack of documentation for poorly factored code.
Instead of "If these idiots would just have documented...", think "If these
idiots would just have writen Unit Tests or Contracts, written clear code
with short methods and discriptive naming, used codeing conventions like
verticle alignment, used comments when the intent was not obvious, and
documented thier intent in a short and concise manner."
"Individuals and interactions over processes and tools
Working software over comprehensive documentation
Customer collaboration over contract negotiation
Responding to change over following a plan
That is, while there is value in the items on
the right, we value the items on the left more."
And don't give me any of that I"Rational" propoganda please.
Jan
Agile Maru
=====
_________________________________________________
Jan William Coffey
_________________________________________________
__________________________________
Do you Yahoo!?
Yahoo! Calendar - Free online calendar with sync to Outlook(TM).
http://calendar.yahoo.com
_______________________________________________
http://www.mccmedia.com/mailman/listinfo/brin-l
