Coding Standards

Introduction

The purpose of this document is to lay out a clear set of guidelines for developing code for TRIBiQ CMS. The scope of this document is limited mainly to PHP code, but it also includes MySQL and HTML.

The importance of coding standards

Coding standards are important for a number of reasons:

• 80% of the lifetime cost of a piece of software goes to maintenance.
• Hardly any software is maintained for its whole life by the original author.
• Code conventions improve the readability of the software, allowing engineers to understand new code more quickly and thoroughly. If you ship your source code as a product, you need to make sure it is as well packaged and clean as any other product you create.

Acknowledgments

This document has been largely created by culling information from the following documents:

• Code Conventions for the JavaTM Programming Language

• Pear Coding Standards

• phpBB Coding Standard Guidelines

• PHPDoc

If you modify and redistribute this document please maintain the above credits and give us some also. It was mostly written by Bharat Mediratta with input from Chris Smith, Matthew McEachen, Jesse Mullan and Beckett Madden-Woods.

Editor Settings / Scripts

At Tribal Limited we recommend BBEdit text editor.

This is a Mac-only editor.

Indentation

Four columns is our basic unit of indentation. The most efficient way to achieve this is to use a mixture of 4-column tabs, as in the example below:

function myFunction() {
   /* a 4-space tab */
   code;
   code;

   if (indentAnotherLevel) {
       /* 2 tabs */
       moreCode;
       moreCode;

       if (indentAnotherLevel) {
           /* 3 tabs */
           moreCode;
           moreCode;
       }
   }
}

Admittedly the use of tabs can mean that when you use a Unix program like vi, less or cat, your code will get spaced differently. But after sticking to this practice for enough years I have to say this is a small compromise and the use of tabs really speeds up coding while in BBEdit.

Line Length

Avoid PHP lines greater than 100 characters.

Wrapping Lines

• Break after a comma.
• Break before an operator.
• Higher-level breaks are preferred to lower-level breaks.
• Align the new line with the beginning of the expression at the same level on the previous line.

Here are some examples of breaking function calls:

   someFunction (longExpression1, longExpression2, longExpression3,
       longExpression4, longExpression5);

   var = someFunction1 (longExpression1,
       someFunction2 (longExpression2,
           longExpression3));

Following are two examples of breaking an arithmetic expression. The first is preferred, since the break occurs outside the parenthesized expression, which is at a higher level.

   /* BETTER */
   longName1 = longName2 * (longName3 + longName4 - longName5) 
       + 4 * longname6;

   /* AVOID */
   longName1 = longName2 * (longName3 + longName4
       - longName5) + 4 * longname6;

Line Termination

Ensure that your editor is saving files in the Unix format. This means lines are terminated with a newline, not with a CR/LF combo as they are on Win32. Any decent Win32 editor should be able to do this, but it might not be the default setting.

Naming Convention

Naming conventions make programs more understandable by making them easier to read.

In the block below, we'll refer to a capitalization strategy called StudlyCaps. In this strategy, multiple words are combined into one where the beginning of each internal word is capitalized. Acronyms are capitalized like regular words. For example a variable expressing the "maximum cpu speed" would be called $maximumCpuSpeed.

Type	Description	Example
Files	File names are in lowercase with underscores. Try to keep your file names simple and descriptive. Files that can be viewed directly by the browser should terminate in .php or .html. Files that are only intended to be included or required, should end in .inc. This is a security precaution to prevent code from being run out of context. Templates should end in .tpl.php.	alias_urls.php
Variables	Variables are in camelNotation and should have a lowercase first letter. Variable names should be short yet meaningful. The choice of a variable name should be mnemonic -- that is, designed to indicate to the casual observer the intent of its use. One-character variable names should be avoided except for temporary "throwaway" variables such as loop indices.	var $userInformation;
Functions	Functions are in camelNotation and should be verbs. Functions that return boolean values should be in the form of a question as in isEnabled.	function someFunction()
Constants	The names of constants should be all uppercase with words separated by underscores (_).	define ("DEFAULT_URL", "www.your-tribal-site.com");
Database Tables	Table names should use lowercase with underscores with the first letter capitalized. Sorry to all purists, but we like words to be pluralized. Table names should be prefixed by something which identifies which application they belong to, e.g. "tribiqcms_".	tribiqcms_template_params tribiqcms_users
Database Fields	Field names should use lowercase with underscores.	id username modificationTimestamp linkId

Top of Page