PL/SQL Standards

Prev	Chapter 9. Engineering Standards	Next

+ +PL/SQL Standards

Prev	Chapter 12. Engineering Standards	Next

PL/SQL Standards

By Richard Li and Yon Feldman

OpenACS docs are written by the named authors, and may be edited @@ -11,25 +11,25 @@ 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: -

General

+
General
1. 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 download and browse the source code. So document like you are - trying to impress your "Introduction to Programming" professor or + trying to impress your "Introduction to Programming" professor or TA. -
2. +
3. It is important to be consistent throughout an application as much 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. -
Code
1. +
Code
1. Encapsulation of related fuctionality is key to maintainability and upgradeability of our software. Try to bundle your code into - packages + packages whenever possible. This will make upgrading, bug fixing, and customizing, among other things, a possibility. -
2. +
3. 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: @@ -53,32 +53,32 @@ / show errors -
4. - Always use create or replace procedure|function - <proc_or_func_name>. It makes reloading packages much +
5. + 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. -
6. - Always qualify end statements, i.e., the - end statement for a package should be end - <package_name>;, not just end;; same +
7. + Always qualify end statements, i.e., the + end statement for a package should be end + <package_name>;, not just end;; same goes for procedures, functions, package bodies, and triggers. -
8. - Always use the "show errors" SQL*Plus command after each PL/SQL +
9. + Always use the "show errors" SQL*Plus command after each PL/SQL block. It will help you debug when there are compilation errors in your PL/SQL code. -
10. +
11. 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.)
-      
+      
         instead of
-      
+      
         acs_user.create(first_names_in => 'Jane', last_name_in => 'Doe', etc.)
-      
+      
      
 
```
  To achieve this we must fully qualify arguements passed into @@ -107,23 +107,23 @@ / show errors -
12. - Explicitly designate each parameter as "in," "out," or "inout." -
13. +
14. + Explicitly designate each parameter as "in," "out," or "inout." +
15. Each parameter should be on its own line, with a tab after the parameter name, then in/out/inout, then a space, and finally the datatype. -
16. +
17. Use %TYPE and %ROWTYPE whenever possible. -
18. - Use 't' and 'f' for booleans, not the PL/SQL "boolean" datatype +
19. + Use 't' and 'f' for booleans, not the PL/SQL "boolean" datatype because it can't be used in SQL queries. -
20. - All new functions (e.g., acs_object.new, - party.new, etc.) should optionally accept an ID: +
21. + All new functions (e.g., acs_object.new, + party.new, etc.) should optionally accept an ID:
```
 
-      
+      
         create or replace package acs_object
         as
             function new (
@@ -134,22 +134,22 @@
                 creation_ip     in acs_objects.creation_ip%TYPE default null,
                 context_id      in acs_objects.context_id%TYPE default null
            ) return acs_objects.object_id%TYPE;
-     
+     
     
 
```
  - takes the optional argument object_id. Do this to + 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, tehy have already gotten an - object_id and now they want to create the object with - that object_id. -
Style
+ object_id and now they want to create the object with + that object_id. +

Style

Some general style guidelines to follow for the purpose of consistency across applications. -

+
1. 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. -
2. +
3. Lowercase everything, with the exception of %TYPE and %ROWTYPE.
($Id$)

Prev	Home	Next
ACS File Naming and Formatting Standards	Up	Variables

docs@openacs.org

View comments on this page at openacs.org

PL/SQL Standards

PL/SQL Standards

General

General

Code

Code

Style

Style