Version 1.0

Anteil Programming Style Guide

Document Index:
0. Design
1. Comments
2. Function Declarations
3. Compound Statements
4. Naming
5. Constants
6. Variables
7. Long Lines
8. Expressions
9. Output Function
10. Inline Data Value Tags
11. PHP Tag Use
12. Idioms
13. Error Handling
14. Database Access Methods
15. User Access Control
16. Script File Extension


Coding Style Guidelines


0. Design
Code that can be understood in a glance has a major impact on its future growth and maintanence.  When code is organized into layers, patterns emerge providing a clarity of design.

The three fundamental layers of Anteil are presentation, business logic, and database.  Database access is constrained through the client/server interface, making the layer very distinct.  However, separating the business logic from the presentation requires extra effort.

The example below demonstrates a clear separation between the business logic (php code) and the presentation (html with php variables).

<!-- Business Logic Layer -->
<?
  $title="My Web Site";
  $whoami=$REMOTE_USER;
?>
<!-- Presentation Layer -->
<HTML>
 <HEAD>
   <TITLE><?=$title ?></TITLE>
 </HEAD>
 <BODY>
   Welcome <?=$whoami ?>
 </BODY>
</HTML>


This example extends the concept where we are generating html.
<!-- Business Logic Layer -->
<?
$title="My Web Site";
$whoami=$REMOTE_USER;
function make_table( ) {
  $rows="";
  for( i = 0; i < 10; i++ ) {
    $rows=$rows . "<TR><TD>$i</TD></TR>\n";
  }
  return( "<TABLE>" . $rows . "</TABLE>" );
}

if( $table_res = make_table() ) {
	....
}
else {
  $table_res = "Error";
}
?>
<!-- Presentation Layer -->
<HTML>
  <HEAD>
    <TITLE><?=$title ?></TITLE>
  </HEAD>
  <BODY>
    Welcome <?=$whoami ?>
    <P>
    <?=$table_res ?>
  </BODY>
</HTML>

1. Comments
Every file should start with a comment block describing its purpose, version, author and a copyright message. The comment block should be a block comment in standard JavaDoc format.
/**
 * This is a test program
 * @version 1.0
 * @author Leon Atkinson leon@clearink.com
 * @date 1/1/2000
 */
Every function should have a block comment specifying name, input/output, and what the function does.
/**
 * description text line(s)
 * @param a how many fingers 
 * @param b how many thumbs
 * @return number of hands added to arm
 * @exception error condition all thumbs
 */
function doAdd($a, $b) {
        return(a+b);
}
Ideally, every while, if, for or similar block of code should be preceded by a comment explaining what happens in the block. Sometimes this is unnecessary.
// get input from user char by char
while(getInput($inputChar)) {
        storeChar($inputChar);
}
Explain sections of code that aren't obvious.
//TAB is ASCII 9
define(TAB, 9);

// change tabs to spaces in userName
while($index=0; $index < count($userName); $index++) {
        $userName[$index] = ereg_replace(TAB, " ", $userName[$index]);
}


2. Function Declarations
As previously stated, functions should have a comment block explaining what they do and their input/output. The function block should align starting at the left margin unless the function is part of a class definition.   All indenting should be done with tabs.  Users should set their editors tab width to their indenting preference.
 

3. Compound Statements
Flow control primitives (if, while, for, ...) should be compound statements, even if they only contain one instruction. Like functions, compound statements should have opening braces that start at column zero relative to scope.

Code within the braces forms a new scope and should be indented.

// tell the user if a is equal to ten
if($a==10) {
        printf("a is ten.\n");
}
else {
        printf("a is not ten.\n");
}


4. Naming
In names which consist of more than one word, the words are written together and each word starts with an uppercase letter.  Function names should use underscores to separate function names from include file name prefixes or suffixes.

5. Constants
Values that are treated as constants, that is, not changed by the program, should be declared in the beginning of the scope in which they are used. In PHP this is done with the define function. Each of these constants should be paired with a comment that explains use. They should be named exclusively with uppercase letters, with underscores to separate words. You should use constants in place of any arbitrary values to improve readability.
// maximum length of a name to accept
define("MAX_NAME_LENGTH",  32);
print("Maximum name length is " . MAX_NAME_LENGTH);


6. Variables
Variables are to be declared with the smallest possible scope. This means using function parameters when it's appropriate.


7. Long Lines
Lines should not exceed 78 characters. Break long lines at common separators and align the fragments in an indented block.
if(($size < 0) OR
   ($size > max_size) OR
   (isSizeInvalid($size))) {
        print("Invalid size");
}


8. Expressions

9. Output Function
Output will use the echo function as show below except where special formating is required, when the use of printf is acceptable.

Output example

  echo ("<B>Output Text Example</B>");

10. Inline Data Value Tags
The use of <SQL> is deprecated.  All inline data values should use the PHP4 convention of <?= $var ?>.


11. PHP Tag Use
This project will use the <? opening PHP tag exclusively.


12. Idioms
Following are idioms you ought to use when appropriate. Often there are multiple ways to perform a task. Using an idiom will make the code instantly familiar.

Looping over associative arrays
//print all address fields
reset($AddressInfo);
while(list($key, $value) = each($AddressInfo)) {
        print("$key is $value<br>\n");
}


13. Error Handling
class Error
error->add($errorId,debugMessage,userMessage) Push and error into the error logging system.
error->clear() Clear pending error buffer.
error->log() Post errors in buffer to log database.
error->display() Display error messages, log and clear error buffer.



14. Database Access Methods
We will use a database abstraction wrapper to allow smoother database access.
class Db
db->connect() Open a connection to the database.
db->disconnect() Close an open connection to the database.
db->query() Run a query against the database.
db->fetchObject() Return a row from a query on the database.
db->freeResult() Release the result of a query on the database.
db->write() Write (INSERT OR UPDATE) a replicated row to the database.
db->seek() Move the cursor in a result set returned by a db->query.


15. User Access Control

user->User()
getLoginBox()
hasPriv($groupId)
id()
logout()
user->userLogin()


16. Script Filename Extension
The use of the .php3 extension is deprecated. All PHP scripts will end with the .php extension.



This document includes documentation developed by the Working-Dogs.com http://www.Working-Dogs.com
and is used under provisions of their license version 1.1. Portions copyright 1999 by Working-Dogs.com.


Version 1.0