| Prev | Chapter 12. Engineering Standards | Next |
|---|
+
By Richard Li and Yon Feldman
- OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. -+</authorblurb> + +
Like any other part of the OpenACS, PL/SQL (or pl/pgsql) code must be maintainable and professional. This means that it must be consistent and therefore must abide by certain standards. The standards will ensure that our product will be useful long after the current people building and maintaining it are around. Following are some standards and guidelines that will help us achieve this goal: -
+
+ +All PL/SQL code must be well documented. We must write code that is maintainable by others, this is especially true in our case because we are building an open source toolkit than anyone can @@ -23,7 +33,14 @@ as is possible given the nature of team development. This means carrying style and other conventions suchs as naming within an application, not just within one file. -
Encapsulation of related fuctionality is key to maintainability and upgradeability of our software. Try to bundle your code into packages @@ -33,7 +50,9 @@ When creating functions or procedures use the following template, it demonstrates most of the guidelines set forth in this document that correspond to functions and procedures: -
+
+
+
create or replace procedure|function <proc_or_func_name> (
<param_1> in|out|inout <datatype>,
@@ -53,7 +72,9 @@
/
show errors
-+ + +
Always use create or replace procedure|function
<proc_or_func_name>. It makes reloading packages much
easier and painless to someone who is upgrading or fixing a bug.
@@ -70,8 +91,10 @@
Name parameters as simply as possible, i.e., use the column name
if the parameter corresponds to a table column. We're deprecating
the v_* and *_in syntax in favor of named parameters notation:
-
+ ++ ++acs_user.create(first_names => 'Jane', last_name => 'Doe', etc.)@@ -80,15 +103,19 @@ acs_user.create(first_names_in => 'Jane', last_name_in => 'Doe', etc.) -+
To achieve this we must fully qualify arguments passed into procedures or functions when using them inside a SQL statement. This will get rid of any ambiguities in your code, i.e. it will tell the parser when you want the value of the column and when you want the value from the local variable. Here is an example: -
+
+
+
create or replace package body mypackage
.
.
@@ -107,7 +134,9 @@
/
show errors
-+ + +
Explicitly designate each parameter as "in," "out," or "inout."
Each parameter should be on its own line, with a tab after the @@ -121,8 +150,10 @@
All new functions (e.g., acs_object.new,
party.new, etc.) should optionally accept an ID:
-
+ ++ ++create or replace package acs_object as @@ -136,20 +167,38 @@ ) return acs_objects.object_id%TYPE;-+
takes the optional argument object_id. Do this to
allow people to use the same API call when they are doing double
click protection, that is, they have already gotten an
object_id and now they want to create the object with
that object_id.
-
Some general style guidelines to follow for the purpose of consistency across applications. -
+
+ + +Standard indentation is 4 spaces. Our PL/SQL code is not only viewable in the SQL files but also through our SQL and PL/SQL browsers. This means that we should try to make it as consistent as possible to all source code readers.
Lowercase everything, with the exception of %TYPE and %ROWTYPE. -
($Id$)
+ +