Forum OpenACS Development: Re: Best Practices / Conventions / Hidden Features / Howto Document for OpenACS

This is kind of off topic, but this comment really rubbed me the wrong way:
One might argue (as XP does) that if you can't read/understand source code, you have no business working with it at a technical level.
Utter nonsense - a meaningless straw man argument. I can always read and understand what code does. (Eventually anyway, at worst. Algorithms so intricate and tricky that understanding the implementation is truly beyond all but a select few are probably extrememely rare.)

What I cannot ever get from just reading the code, is why the code does that - why the programmer chose to do it that way. What was his thinking, and what design/implementation goals led him to write that code? Is that weird looking bit because the programmer just wasn't very good, or is it a critical but subtle bug fix that a master programmer put it in, but never bothered to comment as such?

That sort of "why" information is what needs to go into good code comments. IMNSHO that's the by far the single most important thing to go into comments. Probably that applies to developer docs too. Certainly, developer docs should have all the big picture orientation stuff - what are all the moving parts, what parts do what, why do they do that, what bodies of code are relevent to each part, that sort of thing.

[End rant.]


Despite you feverent language, its not actually utter nonsense. In actual fact it forms part of the basis of a well know (and widely implemented) development methodology.

And, if I could just refer you to my earlier post in its entirety I think I did point out this applies only to techncal docs, not user guides/overviews etc.. i.e. one may as well, in projects like this, avoid the lenghy design docs that server little purpose after the code is released.

But thanks for misrepresenting what I said :o) How good  it is to be be back ...

I cannot imagine that this well known methodology advocates leaving a developer who needs to work with existing software written by someone else totally clueless about the purpose of that software. I think the typical 'Big Picture' paragraph at least is essential for every OpenACS package - why should other developers waste hours finding out what the original author could provide in a few minutes? But propably we agree on this anyway, it's just not really clear to me from the previous comments.
We do agree. I'm referring to technical desing documents. whihc at best shuld be minimal if at all. A design document is useful *prior* to implementation, but not afterward.

At least in this kind of project. I'm sure building software for missle guidance systems or airline operation requies a different approach, but thats hardly relevant here ;o)

Besides, reading code is actually quicker (and weill certainly be a true system description).

Ok, I'll accept that in an ideal world, with infinite resources that can work at the speed of light, then having perfectly matched documents is good.

But as thats not the case, whats the point of aimn at the unattainable, better to work with human nature and circumstance?