Forum OpenACS Development: What naming conventions to follow?

Collapse
1: What naming conventions to follow?
Posted by Mohan Pakkurti on 05/17/01 11:54 AM
Hej,

I have started to work on the faq module, and have done work on the data-model. The faq module uses naming conventions that are different from the rest of the modules. For example:

The function for a new faq is called new_faq instead of the name new which seems to be the name used to create a new object in a package as followed elsewhere. So, how does one transform non-standard names during porting. Change them in the original Oracle sql file and then follow the porting recomendations, or just leave the Oracle files intact, and then somehow accomodate the different names in the port to postgresql.

I would like to change the original oracle datamodel to conform to the naming standard used in the other modules. Is that recommended?

Collapse
2: Response to What naming conventions to follow? (response to 1)
Posted by Don Baccus on 05/17/01 09:06 PM
Yes, I think you've got the right idea.  It would be preferable to use the convention used elsewhere, so if you've got the time and the inclination, please make the change!
<p>
One wrinkle - we're trying to make upgrade SQL files when we change things, so existing ACS 4.2 users (both of them?:) can move a site over easily if they want.  So you want to write an SQL script to drop the old procs and add the new ones and put it in sql/oracle/upgrade.  We've been calling our new version "4.2.1" at the moment, for lack of any better idea, so a "4.2-4.2.1" upgrade script would be just the ticket!
Collapse
3: Response to What naming conventions to follow? (response to 1)
Posted by Domingo Alvarez duarte on 05/18/01 08:18 PM
When porting PL/SQL functions I'm using a "p_" in front of parameter variables names it makes the names shorter and I expect it to mean "parameter".
Collapse
4: Response to What naming conventions to follow? (response to 1)
Posted by Don Baccus on 05/19/01 06:53 PM
Well ... we really want to follow *one* convention, Domingo.  If you can convince everyone to follow that convention, that's fine with me (and I actually like it) but many, many packages have already been ported using the other convention, so there will be some work involved to move everything to a new convention if we adopt one.

The real team approach to things like this is to raise the issue for discussion rather than going off quietly on your own doing something differently than is being done in the rest of the toolkit.

Collapse
5: Response to What naming conventions to follow? (response to 1)
Posted by Luke Pond on 05/19/01 07:38 PM
I'm also in favor of disambiguating parameter names in plpgsql with the "p_" prefix.  It's easier to read than "function_name__", especially when the function name is something besides "new".  It also visually matches the convention of "v_" as the prefix for local variable names (which is occasionally followed by arsdigita).

It's not too late to reach a consensus among the non-core package porters, and put this in the Guidelines document as a coding standard.  Since there's nothing in there at the moment, people will inevitably make up their own schemes for parameter and variable naming.

Collapse
6: Response to What naming conventions to follow? (response to 1)
Posted by Don Baccus on 05/19/01 07:45 PM
Right, I like it too ... let me check with Dan, who probably has the biggest investment in existing stuff.

I could live with a "one or the other" approach, too, for now - I want  code to get ported.

Collapse
7: Response to What naming conventions to follow? (response to 1)
Posted by Domingo Alvarez duarte on 05/20/01 01:56 PM 
Another thing that I saw usefull is to preserve the parameters name
and type with a comment so when we need to use that function is only 
a matter of cut and paste that part and fill in the values in the 
correct order.

create function wap_user_agent__new (
    integer,            -- v_user_agent_id      in wap_user_agents.user_agent_id%TYPE default null,    varchar,            -- v_name               in wap_user_agents.name%TYPE,
    varchar,            -- v_creation_comment   in wap_user_agents.creation_comment%TYPE,
    boolean,            -- v_active_p           in wap_user_agents.creation_comment%TYPE default 't    integer,            -- v_creation_user      in acs_objects.creation_user%TYPE,
    varchar             -- v_creation_ip        in acs_objects.creation_ip%TYPE
  );
Collapse
8: Response to What naming conventions to follow? (response to 1)
Posted by Don Baccus on 05/20/01 03:32 PM
That's fine, too, though I really wish we could convince the Postgres people that having that kind of parameter definition directly in the parameter list would be useful.  There's a patch that allows it that has apparently been vetoed because Tom Lane doesn't think it's useful.

Thanks for mentioning this idea.  A comment such as you suggest would simplify switching over to that style parameter definition if the PG folks change there mind.