Coding Standards

Introduction

The purpose of this document is to lay out a clear set of guidelines for developing code for Zenario. The scope of this document includes PHP, MySQL and HTML.

Editor Settings / Scripts

At Zenario we recommend using either the TextWrangler or BBEdit text editor for Mac.

If you're using Windows then we would recommend using either the Atom or Sublime Text text 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;
       }
   }
}

(Many of the examples you see on the Zenario website use 4 spaces in place of a tab to avoid various browser issues with tab-width; we recommend using actual tab characters rather than spaces in the code you write.)

Line Length

Try to avoid line of code longer than 130 characters.

Wrapping Lines

Here are some general guidelines for 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;

Note that these are guidelines only; when in doubt it's always best to go with whatever is the most readable.

Strings

Strings of HTML or SQL code should contain new lines and indenting such that it reads nicely when read with the PHP code around it.

When building a string of SQL code, you should use whitespace within the code as long as the whitespace will not cause an error.

When building a string of HTML that is interspersed with PHP it is important to maintain the indenting of the PHP so that the logic may be easily followed.

If whitespace in the string will cause an error, terminate the string, use a "." or a ",", and then resume on the next line.

Comments

Always use single line comments for comments that are only a single line. This enables you to comment out blocks of code that contain single line comments.

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 Windows. Any decent Windows editor should be able to do this, but it might not be the default setting.

Note that we make an exception for the readme files included with the CMS and use the Windows line breaks. This is because of a bug in the default text editor included with Windows.

Naming Convention

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

"Dummy" Variables

Consider carefully when to use "dummy" variables that aren't actually needed by the logic. If they make the code easier to read, then consider using them. But if they throw up a cloud of dust and make the code harder to read, then do not use them.

Efficient Memory Usage

You should take steps to ensure that your code uses memory efficiently.

For example, you should rarely use a SQL query of the form:

   SELECT * FROM table;

when you could instead use a query of the form:

   SELECT column1, column2, column3 FROM table;

Where the second query is much more memory efficient, as only the needed rows are returned.

(Note that using getRows('table', true, ...) is the same as a SELECT *)

You should never use the mysql_fetch_array() function in PHP, as this returns each column twice. Always use either the mysql_fetch_assoc() function or the mysql_fetch_row() function.

When defining functions, consider whether you should pass parameters by reference. Consider the following example:

  function myFunction($string) {
      return str_replace('a', 'b', $string);
  }

In some cases, this could be rewritten as:

   function myFunction(&$string) {
      $string = str_replace('a', 'b', $string);
  }

to save needlessly creating a copy of the value of $string.

Warnings and Notices in PHP

PHP can be configured to display warnings and notices for coding errors. At best these look ugly and unprofessional when viewed upon a page, but at worse can completely break functionality (for example, warnings and errors will result in invalid images/JSON/XML when if one occurs when generating an image/AJAX response/RSS feed).

Your PHP code should be free of errors, and not generate warnings or notices.

Prior to version 6.0.3, the default configuration was not to show notices or strict errors. From Zenario 7.0.0, the default configuration is to display strict errors but not to show notices.

Also from 6.0.3, this setting can more easily be changed by a site admin by editing the tribiq_siteconfig.php file. We recommend that Module developers change this option to display both notices and strict errors so they can better pick up problems.