Forum OpenACS Development: Re: Best Practices / Conventions / Hidden Features / Howto Document for OpenACS
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.
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 ...
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?