Synergy 8 Programming Conventions

Conventions are a set of guidelines that developers must abide by to attain cohesive source code across all files in the application.

When multiple developers are working on an application, if conventions aren't standardised, the quality of the source code can degrade.  Degraded source code can be hard to manage and appears unprofessional.

The larger the application, the more important it becomes to standardise source code as manageability becomes an issue. This document should provide a concise set of guidelines to maintain quality source code.

 

 

Conventions for Naming Files

Include Files

The framework consists of many classes and functions to easily create and manage dynamic portions of web pages.  These functions and classes are stored in files that can be included to obtain their functionality.

All include files have the extension .inc.php.   The .inc portion allows you to easily distinguish include files from executable files.  The .php portion of the extension stops users from viewing your source code via http.  PHP will execute the file so if its a library containing a class, nothing will be sent to the client.  This improves security by hiding implementation.

An include file should only ever contain one class.   It is also essential for __autoload to function!   This is a php5 feature that Synergy 8 uses to automatically include a file when a class is not defined.

Examples:

  • functions.inc.php
  • myclass.inc.php

 

Executable Files

Executable files are php scripts that a client may access via their website.  These files should be named appropriately in relation to the functionality that particular script provides.

 Executable files have the extension .php.

 Examples:

  • index.php

 

Conventions for PHP Script Delimiters

When a client requests a PHP script, the web server passes the source code in the script through CGI to PHP.  PHP begins parsing the script from the top to the bottom.  Any non-server executable code is sent directly back to the web server, which sends it back to the client.

There are various ways of marking sections of a script as containing server-side PHP code.

<?php ?> is the most commonly used way of embedding PHP in web applications, and shall be used.  Closing ?> should be removed for class definitions.

 

Conventions for Indentation

A new line should be placed before every new brace.  This is known as one true brace.  Braces should be aligned with the control block gate.  The two braces of a block should be vertically aligned.   Tabs should be used to indent code.  Lines of code shouuld not be longer than 95 characters.

Example:

class MyClass
{
    protected $m_bVariable;

    public function myFunction()
   {
       $arrFruit = array('pear', 'apple', 'bananna'); 
       $bVariable = true; 

       foreach($arrFruit as $strFruit)
       {
            if($bVariable == true)
            {
                // Perform an action
                echo($strFruit); 
            }
        }

       $this->m_bVariable = true; 
   }
}

Conventions for String Quotes

All strings should be surrounded by single quotes.  In PHP programmers can either use single or double quotes to surround string literals.  The double quoted version parses the string for embedded variables, and as such, is slower.

Examples:

  • $strName = 'fred';
  • $strFullName = 'fred' . $_POST['lastname'];


Conventions for Naming Classes

All new words should begin with a capital letter.

Examples:

  • class MyClass
  • class HTMLForm

 

Abstract Base Classes

Abstract base classes are classes that cannot be instantiated.  Only child classes implementing all abstract method signatures can be instantiated.

Abstract base classes should be suffixed with ABC.  This keeps the abstract base class at the top of the documentation class list when sorted in alphabetical order.

Examples:

  • class SingletonABC
  • class HTMLABC
  • class HTMLFormItemABC

 

Inheritance

 For child classes, the developer should prefix the desired class name with the name of the parent class.

This convention is not as strict as others.  If it is more logical, and neater to omit the parent class from the name, the developer should omit it.  Pedantic conventions serve no-one.  A classic example of this is children of the SingletonABC class.  It would be unclean to have Singleton in front of every singleton class.

The ABC suffix from parent abstract base classes should be omitted.

Examples:

  •  class Parser extends SingletonABC 
  •  class HTMLForm extends HTMLABC

 


Conventions for Naming Variables

The first letter of each new word in the variable name should be capitalized.

The variable name should be prefixed by its type in lower case.

Examples:

  • $arrMyVariable = array();    // Variable of type array
  • $strMyVariable = '';         // Variable of type string
  • $iMyVariable = 0;            // Variable of type int

Do not use underscores in variable names to separate words.  Underscores are used to denote scope.

 

Global Scope

Variables declared in global space are prefixed with g_. 

Member Scope

Variables declared in class level or member level scope are prefixed with m_. 

Local Scope

Variables declared in function level, or local scope, do not require a scope prefix.

Static Variables

Prefixed by s_ 

Examples:

  • static $ms_strMyVariable // Static variable in class member scope
  • static $s_strMyVariable  // Static variable in local scope

If the variable is declared in local or global space, no variable prefix is required.  A prefix of m_ is required if the variable is declared in the class membership scope.  Because $this is not implied by the compiler, it must always be used when referencing the current instances members.

Examples:

class MyClass
{
    protected $m_bVariable;

    public function myFunction()
   {
       $this->m_bVariable = true;
   }
}


Creating Functions

Global functions

Global functions should not be used unless they are stored in functions.inc.php and provide extensive functionality to the framework and components.

Encapsulate functions inside classes.  If they need to be called without having an instance, use the static modifier.

The singleton design pattern may also be of use.  See singleton documentation.

 

Member functions

When writing member level functions that is functions that are members of a class, it is convention to write the mutator (setMyValue) before the accessor (getMyValue).

Functions should always have the public / private / protected modifier for clarity. 

Documenting Files, Classes and Functions

Punctuation should be used on sentences in both the label and the description portion.  Punctuation should not be used on @param and @return tags.

Mutator functions

Mutator functions change the state of the current object.

    /** 
     * Sets my value
     *
     * MyValue is a value used by me to perform a specific function
     *
     * @param string $strMyValue My value
     */ 
    public function setMyValue($strMyValue)

 

Accessor functions

Accessor functions make no changes to the state of the current object.

    /** 
     * Returns the current my value
     *
     * @see setMyValue for the purpose of my value
     * @return CDatabase Current my value
     */
    public function getMyValue();