Forum OpenACS Development: Re: Tipping of coding practices ?

Collapse
Posted by Andrew Piskorski on
Tom, PL/SQL (or PL/pgSQL) code is always better off in separate files from "create table" statements. There is never any drawback to organizing things that way, and if you ever need to write upgrade scripts for the PL/SQL code, you will soon find just how much easier and cleaner it is to have the PL/SQL in its own files. Back in July, Malte at least seemed to agree with me, on that, and at the time I also made some very specific draft guidelines (which were mostly ignored).

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.

Collapse
Posted by Randy O'Meara on
Andrew,

RE specific draft guidelines. I certainly appreciate these guidelines. I have since "refactored" my own code to implement your proposed standard layout.

Thank you,

Randy

Collapse
Posted by Tom Jackson on

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.