Hi,

I would like to make a Top 20 list of what you should do or dont while developing in OpenACS. Its goals are:

• Help new and old developers about standards in a short doc.
• Help developers read the real docs since the list will link to the real docs if possible.
• Hopefully start a new chapter or new doc if one items is missing from the real docs we have.
• Hopefully I make a good contribution with least effort.
• The list will set a good guidline for future developments. And maybe the older code will change in time.

It all started with this thread. I am sure there are other older threads that should have made it into the doc.

To make things simple we will first just have the first 5, after it has been establish we will get the next 5 and so on.

Here is the first five that will make it into the list if nobody objects: (I will add more detail on the real doc)

• Use Namespace (ex. foo::get_title, etc.) blah blah.
• Use return_url as the var name if it will be used to return url... blah blah.
• Avoid putting in tcl logic on adp pages if possible. Use foo.tcl and foo.adp. The same way is true for tcl... avoid putting in html on tcl.
• Use package_key__foo or package_key.foo for db api. Use package_key::foo for tcl api.
• Use ad_form... blah blah.

If all 5 items are valid and correct I will put them in. Also if anyone can put a good 1 - 2 liner write up on any items above please post them up. A link to the documentation is also desired. I am more that happy to use them rather than come up with my own.

Thanks very much Vinod.  I will use your list as the next 5.

Also it seems that Namespace is already validated by Yon on the namespace thread.  So 4 to go... and next batch of 5 will be next.

Thanks Yon.

I will put that for the 3rd batch.  I welcome new items please don't get me wrong.  But would like to validate first the first batch.  Don't want to put in the doc that is wrong.

Can someone validate the first 5?  After 2 days I might put those into writing and move on to Vinod's list.

I think the document would be especially helpful (to me anyway) if the items (conventions and standards) are organized by context: tcl (programming, as used in adp), SQL (pgSQL, SQLplus) etc.

Jun, perhaps something from this thread will be useful: http://openacs.org/bboard/q-and-a-fetch-msg.tcl?msg_id=0003wU&topic_id=11&topic=OpenACS

Torben,

Thanks for the link.

Stephen,

You are right that these are bugs and inconsistencies.  I am not saying that this doc will cure it.  I just wanted to try something that MIGHT be helpful.

Great start, thanks, Jun.

One comment: Do not use "==" in comparing strings:

use [string equal ..] instead of [string match ...]

/Lars

Hi Lars,

I was aware of the == problem, but I've been using [string match ...] all over the place! Why do you suggest "equal" instead of "match"?

The section about Tcl in ADP's and HTML in Tcl code; how about some examples or alternatives here?  How should people achieve this?  Probably need something about when and why to register ADP tags, for example instead of calling a proc in an ADP; and when to use registered tags or included templates, instead of embedding HTML in Tcl.

The thing about return_url comes under the more general heading of naming.  For instance should it be mentioned that boolean variables have a _p affix?

When deleting queries from Tcl files perhaps we could replace the query with the literal string *SQL* rather than "" or {}.  If you make a mistake and the correct query can not be found from the .xql file, the blank error message can be a little confusing, but with *SQL* it's more obvious what has happened.

Why must plpgsql function parameters be prefixed with p_?  I don't remember seeing this used already in the toolkit, and we don't prefix Tcl parameter names with p_.  Variable names are prefixed with v_ because you can't assign a new value to a function parameter (right?) and so must use a new but simillarly named variable.

I know this is just a draft, but ultimately there probably needs to be a complete document describing how to create upgrade scripts, with a simple link to it explaining that it must be followed.  I think Jon Griffin's your man here...

How about adding in the $ID tags for CVS? That might be a good
addition as well. I'm not sure if this is in the documentation
already.

I will update the list.  I am a bit busy now.  But I would like to add another for your comments.

When using upvar name your var as packagekey_varname. Example:

upvar cms_item_id cms_item_id

That way its unlikely you will step on someone's var.  Another related to upvar.... if can use another method, avoid using upvar.