# moregroupware coding conventions

This is a first step of guidance to a more clear programming. It is taken from the PEAR Coding Standards which can be found at http://pear.php.net/manual/en/standards.php . These are only excerpts from that to make the main parts clear.

## Indenting

Use an indent of 4 spaces, with no tabs.

For UltraEdit 32 (on Windows) Go to Advanced -> Configuration and choose the Edit tab. Check "Use spaces in place of tabs" and enter 4 in the next text field which should say something like "Tab Stop Value" + an excessive bunch of words. If you've already written code with other tab stops follow the above note and then do Format > Tabs to Spaces For hints on other editors go to the URL shown above.

## Naming conventions

Functions and methods should be named using the "studly caps" style (also referred to as "bumpy case" or "camel caps"). Functions should in addition have the package name as a prefix, to avoid name collisions between packages. The initial letter of the name (after the prefix) is lowercase, and each letter that starts a new "word" is capitalized. Some examples:

          connect()
          getData()
          buildSomeWidget()
          XML_RPC_serializeData()

Private class members (meaning class members that are intented to be used only from within the same class in which they are declared; PHP does not yet support truly-enforceable private namespaces) are preceeded by a single underscore. For example:

          _sort()
          _initTree()
          $this->_status

## Constants

Constants should always be all-uppercase, with underscores to seperate words. Prefix constant names with the uppercased name of the class/package they are used in. For example, the constants used by the DB:: package all begin with "DB_".

## Global variables

If your package needs to define global variables, their name should start with a single underscore followed by the package name and another underscore. For example, the PEAR package uses a global variable called $_PEAR_destructor_object_list.

## Control structures

This is a complete if-example:

        if ((condition1) || (condition2)) {
            action1;
        } elseif ((condition3) && (condition4)) {
            action2;
        } else {
            defaultaction;
        }

For switch statements:

        switch (condition) {
        case 1:
            action1;
            break;
        case 2:
            action2;
            break;
        default:
            defaultaction;
            break;
        }

## Function calls

Functions should be called with no spaces between the function name, the opening parenthesis, and the first parameter; spaces between commas and each parameter, and no space between the last parameter, the closing parenthesis, and the semicolon.

Here's an example:

    $var = foo($bar, $baz,
          $quux);

## Comments

Inline documentation for classes should follow the PHPDoc convention, similar to Javadoc. More information about PHPDoc can be found here: http://www.phpdoc.de/ . C style comments (/* */) and standard C++ comments (//) are both fine. Use of Perl/shell style comments (#) is discouraged.

## Including code

Anywhere you are unconditionally including a class file, use require_once(). Anywhere you are conditionally including a class file (for example, factory methods), use include_once(). Either of these will ensure that class files are included only once. They share the same file list, so you don't need to worry about mixing them - a file included with require_once() will not be included again by include_once().

## PHP code tags

Always use <?php ?> to delimit PHP code, not the <? ?> shorthand. This is required for PEAR compliance and is also the most portable way to include PHP code on differing operating systems and setups.

## Using CVS

Include the Id CVS keyword in each file. As each file is edited, add this tag if it's not yet present (or replace existing forms such as "Last Modified:", etc.).

## General script structure

Additions to the PEAR conventions:

      **********
      inclusion:
      **********

      global parameters:

      $myEnv[module] = "contact";
      $myEnv[output] = "html";

      include('MGW_vCard.php');

(export classes and functions that are to be reused in another context to a separate class of file).

      ********
      control:
      ********

      if (isset($dump)){
      dumpVCard($id, $PHPSESSID);
      } else {
      exportVCard($id, $PHPSESSID);
      }

(which will be more complex in other modules, but shows at the beginning of the page what functions to expect)

      ***************
      implementation:
      ***************

      function exportVCard($id, $PHPSESSID){
      ...}
      function dumpVCard($id, $PHPSESSID){
      ...}

Clearly defined interfaces what parameters we need to make the function work and to improve testing of single methods).