Coding & Naming standards for OpenDb
------------------------------------


1) Introduction

Most of these standard practices are followed in the code, however some
legacy code may still be out of standard.  As time permits this will
be rectified.

If you stick to these standards, OpenDb will be far more maintanable.


2) Coding standards

	* Use 4-space TAB indenting. (Use tab character and set your editor 
	* to 4 spaces)
	* Always start your brace off on the next line (C style, not C++)
	* Always use braces around while,for,foreach,etc constructs.
	* Always use braces around if, if you are including anything but
	  the one line statement.  (For example comments)
	* Comment for function should proceed the function, similiar to
	  javadoc comment.
	* Do not use # comments in php, always use C++ style // or /* */ 
	* If you use 'echo', don't use 'print'  (Some older code still
	  has this problem)

3) Naming Standards

3.1) Functions 

    For all database related functions, the following applies:

3.1.1) Prefixes

	fetch_
	update_
	delete_
	insert_
	validate_
        
The name of the table should come next.  For tables with an
s_ prefix, you do not have to include that.
    
If the fetch for instance, returns most of the table, then
you are set.
        
If you only return a couple of columns, then add them to the
function name:
	fetch_user_id_and_fullname
            
If the function joins two tables, include the other tables in
the function name as well.  Use common sense to not overdo this:
        
	fetch_user_item_
            
Finally the suffix of functions is required.  This is only
of importance for fetch_/get_ functions:
        
	_r	For a record (array)
	_rs	A resultset
	_cnt    A int, which is the result of a select count(...) operation.
  
3.2) Non-Database functions
    
For non-database functions, do not use fetch_, but get_ for operations
where you are computing a value.
    
3.3) Variables
    
Where a variable is being returned from a fetch, especially 
a _r, use the same format as for the function name, just remove
the fetch_ prefix.
    
For all others use your discretion.  But I recommend, that if 
you are getting results from a _rs suffix function.  Each time
to use mysql_fetch_array($result), assign it to a _r of the same
prefix (minus fetch_ as the function name)

4)	Editor Configuration (Support OpenDb coding standard 4-space TABS)

4.1) Emacs (Contributor: Andrew Donkin <ard@waikato.ac.nz>)

To make Emacs indent OpenDb PHP in this style, add this to your .emacs:

(defun my-php ()
  (setq indent-tabs-mode t
	tab-width 4
	c-basic-offset 4)
  (c-set-offset 'block-open' - )        ; Block open braces align left, normally 0
  (c-set-offset 'substatement-open' 0)  ; Substatement braces align left, Normally +
  )
(add-hook 'php-mode-user-hook 'my-php)

This will make Emacs use four-wide tabbed indenting for all your PHP files.
If you don't want that, you'll have to put some buffer-local variables in
each of OpenDb's .php files, or add a hack to use Jason's style when the
filename contains the string "opendb".  This is what I use:

(defun my-php ()
  (if (string-match "/opendb/" (buffer-file-name))
      (progn
        (setq indent-tabs-mode t
              tab-width 4
              c-basic-offset 4)
        (c-set-offset 'block-open' - )
        (c-set-offset 'substatement-open' 0 )
        )))
(setq php-mode-force-pear t)
(add-hook 'php-mode-user-hook 'my-php)

This makes Emacs use four-wide tab indenting for OpenDb PHP and PEAR
standard for everything else.
