Forum OpenACS Development: Re: Tipping of coding practices ?

Collapse
10: Re: Tipping of coding practices ? (response to 7)
Posted by Andrew Piskorski on 11/30/03 08:35 PM
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
12: Re: Tipping of coding practices ? (response to 10)
Posted by Randy O'Meara on 11/30/03 08:53 PM
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
11: Re: Tipping of coding practices ? (response to 10)
Posted by Tom Jackson on 12/01/03 12:18 AM

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.