Forum OpenACS Q&A: namespaces: to use or not to use?

I've been developing some OpenACS 4 packages (Paypal, Cookbook, Wiki)
and have been wondering if I should put my procs under namespaces or not.

Some packages use them, while others don't. It seems like a good
practice to use them. Thoughts?

another thought: use them

Would you like to volunteer to do this? :)

There used to be some coding standards from aD for OpenACS 4 lying around their website, I do believe.  They may've even made it into the ACS 4.x distros, does anyone know?

I'd start doing a little searching as a first step if you're interested in spending a little time on this ("foo_p" for predicates, for instance,  was a documented aD coding standard).

I've mumbled to a couple of folks about wanting something like this so would be willing to review anything you come up with and help out by editing, etc.

Hi Torben,

Thanks for the reminding about the doc add a comment feature.  I was only able to add suggestion #3.  The other suggestion seems to be out of place.

Hi Don,

Yes I am willing to volunteer on this.  Just give me new-file-storage access.  I wish to make a small doc titled "Simple OpenACS dos and donts".  That will contain the top 20 or 50 things to do or dont.  Why so little?  The doc is meant for lazy developers like me.  It may or may not work but its worth a try.  I have listed 6 unvalidated suggestions.  I will basically use the bboard to gather the top 20 or 50 things.  And put it in to this simple doc.  Maybe we can add sections to the main documentation from this simple doc.

Hmmm maybe entitle it to be "Simple OpenACS guide for Lazy Programmers".... hehehehe.

Hi Stephen,

Not sure if it will help, but it might.  Its worth a try.  We can just start with 20 things.  Each item may point to some real documentation for further reading.

I think it will help.  Like for example the original question posted by Roberto.  I am sure Roberto read the docs while he edited and added to them. But it seem those docs did not have all the answers or it may have but was deep down in it.

If you think the idea is just a waste of time then I will throw away the idea.  Do you think its worth putting some small doc about the top 20 things we must know?  I am volunteering to maintain the doc and will add the first 5.  Maybe some will add until it reaches 20.

What do you think is worth some volunteer effort?

I was referring to the original question, "should I use namespaces", and the just-cos answers.  I was wondering what the advantage was, as one of the only differences I've noticed is that depending on how the namespaced proc is specified, the api documentation is broken. Oh, and maybe you can't grep for usage of the proc anymore.  Why is ad::conn better than ad_conn?

Sure, a guide sounds great.  Looking forward to it.

stephen:

1) proc name collision avoidance

2) package consistency; i.e. pl/sql package named foo and tcl package named foo

3) ability to call procs by their real name from within a namespace; i.e. within namespace foo i can call function foo::bar by just saying bar, elsewhere i call it with foo::bar

ad_conn is meaningless, ad::conn is also meaningless. i am against putting names of people or companies in proc names. it only adds clutter and needless typing. if it's a matter of ego and recognition stick an @author doc tag in the ad_proc doc argument, which you should do anyway so that people know who to contact about a proc.

namespaces and proc names should be meaningful and should help categorize functionality. take as an example, the new permission:: namespace. newbies (and others) can very easily tell what this namespace is about and how to use it, check out http://yourserver/api-doc/procs-file-view?path=packages/acs-tcl/tcl/acs-permissions-procs.tcl, it's not the best documented package, but it's still fairly clear.

this brings me to another practice i think we should adopt everywhere. one of the reasons i created the new permission:: namespace is the use of named parameters. i think we should all use them everywhere. i have spent countless hours chasing down bugs all over openacs 4.x that boiled down to people passing arguments in the wrong order to functions. one of the common ones is ad_permission_p and it's siblings. this could have been much easier to find and fix (if not avoid all together) if the function had used named parameters. yes they are a longer to type, but i believe that is typing well spent. it helps with code self documentation and maintenance, it helps avoid situations like the one i explained above. i think we should make it a requirement for api's to use named parameters, and that we should slowly move the core to all named parameters, it's not that hard (of course changing acs service contract to use named parameters would be incredibly useful too).

i think those are enough reasons

Hi Stephen,

I don't plan to make my list a do list as I have stated above.  Its just a list that is approved by a good number of knowledgable person for FUTURE development.  (I also take no objection as an approval... the approval doesn't seem to come as I expected them to be).

Anyway atleast with the list future developments will have a better and consistent path.  If (big IF) use of namespace is agreed then future developments will just use it, that rather than what is happening now... some use it some dont.  A concrete example is Roberto's future packages.  If we had this small handy guidline he would not have to ask this question and design and code away.  If we had this guideline I would not have used mypackage_gettitle tcl api.  I would have used mypackage::gettitle since that is in the guidline.

I think what I should do is to state the goal of the doc right on top of the doc.  As not to confuse new developer in looking for ad::conn which does not exist.