Forum OpenACS Development: More language lawyering - parameter naming conventions

Request for comments ..

After perusing the parameters sections of various packages, I was inspired to run some quick greps on the *.info files in the OACS standard install, to see HOW inconsistently things are being named and handled in the OACS parameters. I feel this is VERY important, mainly because the population that plays with these are less likely to be coders than admins, and also because a lot of people get their first impression while they are bringing things up and down in the APM and also because they all appear in more or less the same place.

Anyway, down to business ...

* Parameter name style:
There seems to be a strong tendency with notable exceptions to use InitCap rather than under_score for parameter names.

Recommend - ALL parameters should be made to be InitCap - ditch the underscores.

Looseness in following the ThisIsABooleanP 'P' rule. Again, most packages indicate the predicate, some don't. Some packages do it in all but a few cases.
Recommend - All predicates end with P. I guess until we upgrade to the new AOLserver (and gain "true/false", that means these are ALWAYS 0 or 1 values.

* Parameter name terms - file locations:
The most confusing item encountered is Directory/Dir/Path/Root/Location and other variations (case rule above). Related to this is wide inconsistency in whether a path is absolute or relative and whether, if relative, it is relative to [acs_root_dir] or [ns_info pageroot]. A related MAJOR peeve of mine is parameters named SomethingURL when the parameter is NOT a URL, but rather a local relative path (see lars-blogger for example). It is very hard to discern from the current names what exactly is expected, and what exactly the outcome will be. I think there needs to be a pair of terms we use to mean "local files" and a different set that means "url parts". Again, consistency will drastically cut on confusion.

Recommend - in keeping with current (implied) convention - if the parameter is a directory,leading slash is ALWAYS absolute, no leading slash is ALWAYS relative to either [ns_info pageroot] or [acs_root_dir] (not sure which is right).

Recommend - use the suffix BinDir to indicate local executable locations (ImageMagickPath for example -> ImageMagickBinDir).

Recommend - use the term Dir to indicate a local directory (short and unambiguous enough).
Still open - Dir - should there be a relative/absolute distinction?
Still open - filename component.

Recommend - parameter not be called URL unless there is a Scheme, Host, {URLPath}.
Recommend - Host means either a complete hostname.domainname.TLD or dotted quad IP.
Recommend - use the term URLPath to indicate a parameter that is used to provide the URL path, rather than actual directory.

* Parameter name terms - Dealing with time:
All times are in seconds unless the parameter is called FooInterval{Days,Years,Months,Minutes}.

Without getting into immense detail - I'm sure you get the point by now :) - Time/Interval/Period/Frequency - a consistent naming convention.

* Colors - implied convention that HTML colors are always in the #ffffff format - you need the pound and 6 hex characters (unlike CSS triplet).

For reference ...

RFC 1738 uses these terms
scheme - one of http,ftp,file,gopher, etc...
host - self evident ?
port - usually a default per scheme (i.e. http = 80)
url-path - everything after the host:port part.

Posted by Jade Rubick on
Alfred, I think this is a great set of guidelines. Does everyone agree with his conclusions? If so, I think we should put this in the official documentation.

Alfred, perhaps you can file a bug-tracker to-do to add a write-up from this page to the documentation?

The sooner we do this, the more uniform packages will be in the future.

I passed this by Joel about a month back (finally posted because it was it was getting 'stale' in my local directory as a text file) - I incorporated his comments to some extent.

I'd like to hear other people chime in at which point I'll put together a more 'finished' version for posting.

I guess the right thing to do is wait a week, see who says what, incorporate comments, and I'll probably stick a copy up on one of my websites and stick a note in bugtracker requesting that it go into the docs somewhere.

Thanks for the positive feedback :)

Posted by Don Baccus on
Yes, the more we codify what we consider to be standard practice the better.  None of your written recommendations are controversial and better-written packages already follow (or mostly follow) them.

It would be really great if someone knowledgable would take the time to collect all our "best practices" scattered docs (like Jun's initial effort, the portions of our old porting guide that are still relevant, form building docs, CR docs, etc) into one easy-to-find place ...

Posted by Lars Pind on
Thanks for looking into this, Alfred. It's definitely needed.

Also, I find that it helps to provide examples of acceptable values in the description, and I think we should recommend that people do that.

I just wanted to point to this orthogonal but related piece:

which would further help administrators by providing more rich form-builder based forms for editing package parameters and other similar things, complete with drop-downs, check boxes, radio buttons, and validation, as appropriate.

No implementation has started yet, but if time and funding permits, I hope to sneak it in to 5.0 or 5.1.


Posted by Jade Rubick on
Alfred, do you have any more to post on this? Do we all agree this should go in the documentation?