$Id: STANDARD,v 1.9 2002/05/28 01:30:06 thomasamoulton Exp $

osCommerce Coding Standards

In order to keep the source code sane, a standard has to be followed
in the coding practice.

* Files are to be saved in Unix format.

* TABs should not be used. To indent, use 2 spaces.

* The start and end tags for PHP must be:
  <?php ?>

* Define necessary constants before they are being called
  (ie, in include files)

* All variables should be called within their scope:

  $HTTP_GET_VARS['variable']
  $HTTP_POST_VARS['variable']
  $HTTP_COOKIE_VARS['variable']
  $variable (either local, or session)

* Use include() and require() where appropriate:

  require('file.php');

  if (condition) {
    include('file_true.php');
  } else {
    tep_false();
  }

* Instances of objects should be called as:

  new className;
  
  and not:
  
  new className();

  When parameters are passed, then use:

  new className($parameter1);

* To echo out a string, use:

  echo $variable;

  and not:

  print $variable;
  <?=$variable;?>

* All custom functions should start with tep_

  function tep_my_function($parameter, $optional = '') {
    global $HTTP_GET_VARS, $another_variable;
    
    <function code>
    
    return true;
  }

* Class names should match its lower-cased file-based name: myclass.php

  class myclass {
    var $variable;
    
// class constuctor
    function myclass() {
    
      <method code>
    
      return true;
    }

// class methods
    function do_something() {
    
      $this->variable = 'set';
      
      return tue;
    }
  }
  
  $class = new myclass;
  $class->do_something();

* Database queries should be done in this format:

  $action_query = tep_db_query("select column1, ...");
  while ($action = tep_db_fetch_array($action_query)) {
    echo $action['column1'];
  }

* All functions should return strings and not do any direct
  echoing, for example:

  function tep_my_function($string) {
    return $string;
  }

  and not:

  function tep_my_function($string) {
    echo $string;
  }

* Simple boolean expressions can be written as:

  $string = ($condition) ? 'true' : 'false';

* IF statements should be written as:

  if (condition) {
    tep_do_something('true');
  } else {
    tep_do_something('false');
  }

* Switch-Case statements should be written as:

  switch (condition) {
    case '1':
      tep_do_something('1');
      break;
    case '2':
      tep_do_something('2');
      break;
    case '3':
      tep_do_something('3');
      break;
    default:
      tep_do_something('default');
      break;
  }

Function Comments
-----------------

The support site uses an application called PHPXref which cross-
references inline comments with functions.

PHPXref requires that you comment your files in a certain style
for your entries to be used as documentation.

There are a few different comments that PHPXref recognizes:

1) File description:
   This provides a one line summary of what the file is and will
   show up in the directory listings.  To use it you should place
   one comment near the top of each file in the following format:

// filename.php - This is a description of the file called filename.php

   ie. the line must begin with '//' followed by the name of the
   file, followed by a hyphen and then the description.

   If you need an extra line then add one in the same format:

// filename.php - This is a description of the file called filename.php
// filename.php - that needs two lines to describe it

   You can also designate an author for the file by adding a line
   thus:

// filename.php - author: gareth,james

2) Function description:
   The main reason this script exists is to provide a means of
   documenting each function in use.  Each description consists
   of a one line summary and a long description.

   Example:

////
// !A short summary about what this function does
// A longer, more complete description would go here
// We might include details of what the function parameters do and what the 
// result should be, etc.
function example_function($foo) {
        ...
}

   Points to note: The description must begin with four forward
   slashes "////" on a line by itself.  

   The one line summary must begin with "// !" (note the
   exclamation mark).

   The remainder of the description must begin with "// " on each line

   The function declaration should immediately follow the description.

3) Table references:
   As the parser has no reliable means of determining when you reference
   a database table in your code (ie. you may be referencing by variable,
   etc) you need to give it a hint by using a comment in the following
   style:

// TABLES: table1, table2, table3

   You can insert these comments anywhere in your scripts.  I recommend
   adding them to the end of each function description to note what
   tables that function uses.