Forum OpenACS Development: ad_parameter deprecated in favor of parameter::get?

Jonathan,

Generally using named parameters makes the code more clear and readable. I think that understanding the code after the fact is more valuable than saving a few keystrokes up front.

I think it makes the code more accessible to someone is isn't intimately familiar with openacs, which is huge and takes quite a while to grasp the entire thing.

Another point is that using all named paramters in a proc is more clear than using a few named paramters and a few positional paramters which some of the original procs do.

Anything that makes it easier to learn openacs is a plus.

Hmmm,

Well I would appreciate a wider discussion, all previous discussions seemed to favor named paramters.

Most new code is using this style. Two published development guides point to using named parameters: http://www.infiniteinfo.com/openacs/things2remember.html and http://www.collaboraid.biz/developer/package-developers-guide
although it appears the documentation is silent on this issue.

The developer's tutorial doesn't seem to mention Tcl APIs at all.

Hmm, quite interesting. I would think that required arguments would not need to be named. What would be the point of that? Hey, but the OpenACS style is to flip all the tcl conventions around anyway. Required parameters in ad_procs come after the options, unlike tcl. None of this makes anything easier for the novice OpenACSer, although a complete novice might not notice anything funny.

Jonathan,
I agree with you that the parameter name argument shouldn't have been named. In general though I've found named parameters to enhance readability, both for Tcl procs (ad_proc) and for Oracle plsql procs and functions. I believe the enhanced readability and maintainability is there not only for novices but also for experienced developers.

Jerry,

the solution is simple but requires a slightly different coding practice. First define the namespace like so:

namespace eval mypackage {}

Then create the procedures using their fully qualified name as such:

proc mypackage::get {} {}
proc mypackage::set {} {}

This way etags still works.

/Bart

Yes, by far the predominant practice in the software world, and particularly in tcl, is for mandatory arguments to be un-named.  If you are so worried about making things easier for newbies, write an etags how-to, instead of forcing everyone to type -paramter etc. redundantly.

Don said: "I have no problem with mandatory parameters not being named.  The name-all-params style was begun by Open Force when they began implementing dotLRN, and at the time no one complained (they raised it in the forums)"

I have no problem with that either. But please let's document ALL the params.

-Roberto

Hi,

I also raised that issue too when making the doc.  People had the opition to use -parameter.  I made the doc, I also followed the practice.  I see newer code also does that thing, so in my mind I was following a practice/advice properly.

I gave the doc to Joel and maybe he can decide what to do with it.  Anyway maybe the governance should be a good try for this one.

Hi

I'm a newbie. I prefer named parameters. Objective C doesn't do named parameters per se but makes things quite clear by being able to call something like [initWithName:name andType:type] -- as you can see it's clear what is being passed and it's not always necessary to look up the docs. Named parameters offer much the same sort of value. I much prefer named parameters for readability. Frankly, being new to OACS, Tcl + AOLServer (which most new OACS users would likely be as we all know most of these are unfortunately not widely used today), named parameters make Tcl code MUCH easier to read and get at least an idea of what the code is likely meant to do.

Comparing code of a complex software system to Unix command line is just NOT useful. Unix command line is clearly meant to be fast and not used by novices and not to write software systems in. Come on, how many of us CVS and backup our Unix command line work??!!!  Also Unix was written by and for programmers.

OACS does not have this luxury, it's being used by web developers that most of may never have taken a programming class. At lease we hope it's being used, more and more. It's a great platform, let's make it more useable by everybody and not just the diehard core team. Saving a few keystrokes should not be the concern here. PLEASE!

Not to rant but I've had some frustrating times coming up to speed on OACS and I'm a programmer with a BS degree from UCLA who wrote NeXTSTEP programs for about 15 years!!! It should be a lot easier than it is for us newbies:( I think the little things like documenting code and parameters and return values and errors thrown, etc.... ad nauseum really make a difference here.

thanks for listening:)

Hmmm

I still disagree. Just because Tcl procs in a language don't do it, doesn't mean code in a framework shouldn't do it. They are 2 completely different beasts.

I'll ignore the personal slam about "you are probably this" -- just not pertinent really. It's ok if we disagree and you don't even have to try to talk about what not so good a C or otherwise programmer I am;)

Writing "my_proc -userId $user_id" is not silly. It tells callers that my_proc expects a userId as an argument. That is very helpful. It could expect any sort of data structure representing a user, but it doesn't it expects a userId. 2 different things. And the docs are usually not very explicit in details on parameters and return codes. And sure if you happen to name your userId $user_id then it seems to make sense however, in real code the user id may very well be named anything else from $my_array(1) to $the_dog_ate_my_shorts and then it's not so nice. The other way, the parameter clearly enforces it.

I still think that regardless of what OpenACS is not, it should strive to be useable by as wide a user base as it can. Here's to making a widely used, user friendly, open source, web framework for the masses!

Unless I'm reading someone else's code (or many, many someone elses' code written at all different phases of the frameworks life, when variable naming standards/fashions changed) for examples and their variables are named in some or other historic fashion that makes sense in the greater scheme of what they are used for (the overall goal of the package/form/etc they are writing) but not as individual arguments to every single OACS method call in any other package whose procs they call.

For instance I'm writing a package that sells hamburgers at a drive through window (lightening up the conversation a bit;)
My variables are called drive_through_car, window_guy and order (and so). These make perfect sense in the scenario I am coding for on an overall basis and make it so that I can call my objects what they represent in the real world instead of a language or data structure specific name (user_id, write_privilege_p, whatever).

Now that makes all the code in my package easy to follow and the same object is always called the same variable name across the board. However deeper in my code where I have to call other packages, should I make it clear like this each time I call other code?
set user_id $window_guy
set object_id $cash_register
set privilege_id $cash_register_access
[permission::permission_p  $user_id $object_id $privilege_id]

Or it could look like this:
[permission::permission_p -party_id $window_guy -object_id $cash_register -privilege cash_register_access]

Of course this is just an example and permission::permission_p AFAIK requires named parameters.

It just is not always clear even if you are the ultimate God of writing perfect code (and every other who contributes to the code base is too) and it shouldn't have to be assumed that variable names will make procs understandable. Just like docs and comments aren't always there when ya need them either.

Whatever, it's just an opinion different from your own from someone who might be representative of newer users to your system... who aren't perfect, mean well, and would like any bit of help the code standards might be able to offer them in following the code.

Sorry but I am not following what you are talking about.  "forcing the user to do the IDE's job is a poor idea;" Is this an analogy or does it apply directly to what we're talking?

I also do not understand the references to Notepad, etc. What are the "adequate tools" you are referring to and what are the problems they do or don't solve?

I have lost the point of this thread:(

Anyway, I in no way intended to get involved in some long rant/flame about our personal levels of guru-ness or intelligence...  I honestly thought opinions were being asked of others on their preferences on named parameters. I gave mine. I'm beginning to regret it:(

or just getting bored... or something...

It would be nice if we can decide which one we should use.  And stick with it.

I find it weird that this was only brought up now.  There was discussion about this, the outcome was named parameters.  I am not saying that Jonathan's reason is not valid.  But people did try to follow name parameters and even made crude docs about it.

I liked named parameters because:

- it has -foo:required, but then again if no named parameters will have a convention of all required that is ok.
- it has {-foo "bar"}, its nice to have this shortcut.
- i can add a parameter to an existing proc without breaking existing code.  But then again no name parameters can do this too.

I like no named parameters because:

- as pointed out by Jonathan, it follows the tcl way.
- it reads better for those procs with 1 or few args.

I think we must discuss this what are the plus and minuses and the core group can give its decision.  And the decision be placed in the docs, not to be digged up on this forum.  It has to be a clear guideline.

Frankly I find the comments made to Tammy inappropriate.  It is this very attitude that makes newbies go away.  Also even though that Jonathan volunteer and have cvs access to change  the api.  What about those like us who just read the docs and followed the code and use parameter::get -paramater?  Tough luck for us and our existing code will break on the next upgrade?  And we should replace existing code as well?

Where do we go?  What will be our real guideline for this?

Maybe you could call it a crowd, though ... ahem!

I have no problem having required parameters being unnamed. That is clearly the style that was used on ACS 4 that OpenACS is derived from.

I also am not going to care, but let's have a decision and recommened it in the documentation.

Verbosity and readability are not synonymous.  I've given several examples to this effect but it's like people only have the capacity for one thought: "More typing makes easier for newbies!  Ommmmmmm..."

Jonathon ... can you show us the stone tablets upon which God has written that you are the sole arbiter of programming style?  Your attitude that you're right and others are wrong because you understand good style and others don't is not helpful.

Peter makes a good point: we're not going to go change all the existing API that's been added which use named required parameters (Tom makes a strong point in this regard, too, we don't want to arbitrarily break existing third-party code for relatively trivial issues like a shift in group opinion over good style)

I'll raise your 15 years of C programming experience with my 29 years of C programming experience if it's going to come down to arguments of that sort.

I've said previously I have no objection to not naming required parameters but let's argue on the merits rather than get involved in a dick-measuring contest over who better understands programming style.

This issue was raised earlier and there were no strong objections to Open Force's proposal that we adopt the use of namespaces and named parameters (the style they used writing .LRN)

Frankly I'm more concerned with there being a hodgepodge of styles.  Any style used consistently is better than the current situation ...

Hi,

I think the TIP forum can be used for this?

https://openacs.org/forums/forum-view?forum_id=115570

We have stated our opinions and discussed some merits above.  Clearly I would like to have some set guideline, not a rule.  As Peter pointed out it may differ from case to case.  But a guideline must still be in place.  Otherwise the toolkit will have 2 style of doing things in the future.  We have a mix and mash in the past, we need to correct or minimize this mistake.

I am not exactly sure how things will work at TIP.  Does it work something like this?

- Jonathan puts a proposal
- People will give in feedback
- Core developers will decide
- Joel will document

If so lets try it.

Yep, I wrote my first C code in 1974, to change the terminal interface distributed with PDP-11 Unix to use Dec-standard full-duplex line editing rather than the half-duplex line editing style they'd copied from Multics.

That probably doesn't mean anything to anyone here other than me ...

As far as style goes, "good style" is rarely an absolute.  Within the C community itself, function headers (prototypes) as implemented in other languages were once considered verbose and redundant, a Pascal-ism if you will for the weak of mind.  Yet after C++ introduced function prototypes, the C camp finally warmed up to them, included them in ANSI C, and today the use of function prototypes is considered good style by most, but not all, C programmers.  For example the author of daemon tools apparently is old-camp and refuses to use them, but his view is nowadays the minority view.

So your high-handed "I know better" approach to issues of style shows, among other things, a certain lack of perspective.  When Open Force proposed adopting the named parameter approach, they argued among other things that it was good style ...

Hi,

I think we should move this to TIP.  I also think that Jonathan should be one to put this on TIP.

If not, then what is the coding style of OACS?

Andrew, tcl prcs, those defined with proc, have required parameters first, because they are passed in to the proc in order. Following that are parameters which have defaults defined for them:

proc my_proc { param1 param2 {param3 "a"} {param4 "b"} } {

    # do something

}

But I don't see what you are talking about WRT the string and clock commands. The order is:

• command
• subcommand
• switches
• required_positional_params
• optional_positional_params

The string command does have a few switches which require a value, just like unix command switches. And the order is the same format as unix commands. There are no named parameters in unix commands.

In contrast, db_multirow, defined via ad_proc has optional switches, followed by unnamed positional params, followed by more optional switches, followed by a required 'code_block' param, followed by an optional param:

 db_multirow [ -local ] [ -append ] [ -extend column_list ]
  var-name statement-name sql 
  [ -bind bind_set_id | -bind bind_value_list ] code_block 
  [ if_no_rows if_no_rows_block ]

The final optional param has to be prefixed with a switch that has a distinct format, missing the beginning '-'.

There can always be good reasons for doing things this way, and I'm not passing judgement on the style. I think the procedure comes with enough documentation to quickly figure out how to use it. But it isn't like tcl or unix command style.

It's rather silly to point to the few inconsistencies that exist in any large project and claim this proves that the rest of the code base follows no pattern.

All you have to do is look at how tcl "proc" works out of the box to see what the tcl pattern is.  99.9% of tcl functions are written with proc, after all.  Grasping at straws to demonstrate otherwise is wishful thinking.

before anyone gets too wound up about flaunting the Tcl standards they should read the code in various tk and tcllib procs for handling flags and decide if they like the internals better there.

Personally I don't like having to roll my own parameter parsing and I like the convenience and robustness of ad_procs arg parser (which is really a side benefit and the real advantage is the documentation stanza).

Also, the abomination that is db_multirow is not a consequence of anything planned or of ad_proc or anything else, rather it is in the state it's in because it was modeled on db_foreach (which used proc_doc) and it looks the way it looks since it started life without the ad_proc arg parser, sprouted warts over time and has a combination of internal hand rolled option parsing (the above mentioned "standard" convention) and ad_proc parsing for some things that were added subsequently.

On the other hand I don't see people getting it wrong in their code so I don't think its a problem that it has some cruft.