Forum OpenACS Development: Re: Tipping of coding practices ?
Tom, If you seriously "thought code was documentation" (rather than just engaging in annoying hyperbole), then you are seriously confused. Code, at best, can only tell you what is being done, never why. Explaining the why is, among other things, what comments and documentation are for.
RE specific draft guidelines. I certainly appreciate these guidelines. I have since "refactored" my own code to implement your proposed standard layout.
I don't disagree that pl is easier to maintain in separate files from table create. My point is that it is much more likely that an index would need to be recompiled than for pl. You need three files, not two.
Andrew, documentation is anything that helps the user understand what a program does, or helps a developer fix a bug or add features. For compiled binary files, code isn't much documentation. However source files, including the code, are documentation. I don't think I am seriously confused on this matter, although I wouldn't mind claiming the moniker 'Annoyingly Hyperbolic'.
OpenACS is blessed with a helpful user community willing to explain less than obvious features of the toolkit. This helps make up for the lack of other types of documentation.