Coding Guidelines

Code Guidelines
As part of our goal of keeping information and processes easy to use, we have created this document to explain our coding style at Worklist. It is meant as a guideline to answer any questions about what we like to see in good coding style, and it is loosely based on the PEAR coding standards. A more in-depth version can be found here - Coding_Standards - written in the technese that we all love so much. :)

If you have any questions and don't see the answer here, head to our [Worklist Chat] and ask one of your fellow coders for advice.

This document covers the following topics:

* Platform * Comments * Class and Function Comments * Short Tags * Indent and Spacing * Line Length * Naming * Headers * Portability

Platform
While code should always be designed and written with maximum portability in mind, if there is any reason requiring the presumption of operating system and environment, the target platform should be developed for:

* Modern, Major Red Hat-like Linux Distributions (Fedora 8+, CentOS 5+, Mandriva 2008+, RHEL 5+) * 32-bit Architecture (32-bit will work on 64-bit, but vice-versa may not always be the case) * PHP5 >= 5.2.6 * MySQL5 >= 5.0.45 * Apache 2

Remember, PHP is not threaded, and bad code can quickly and easily bring even a high-end modern system to its knees. As such, the following resource configuration should be considered the maximums available:

* CPU: Single-core Celeron 2.4GHz i386 * RAM: 512MB * HDD: 5400RPM IDE (size unspecific)

Comments
Commenting your code is the most important part of code creation at the LoveMachine. You are one of many who will look into our code, make changes, improvements and add new content. By creating clearly written comments, you ensure others coming after you will sing praises of you to for generations to come! Ok, maybe they will just appreciate the fact your comments make their future tasks easier to accomplish. Keep your comments brief, but descriptive including parameter & function usage and where applicable class, function, etc... usage. We use English as our common language, and prefer you take an extra minute or so to check for good grammar - remember, people may only know you by your comments... Comments must not begin with the hashbang (#) character & may not exceed the maximum line length of 120 characters. Comments should be signed with the date (in DD-MON-YYYY format) and your sandbox username in '<' & '>' brackets. (ex. 05-APR-2010 )

Comment length will determine the formatting for entry. When writing a comment that will fit on three or fewer lines, please use the double-forward-slash method. Example:

// This is a comment that will exceed one line, but // will be less than four lines in total, which will // include name and date. 05-APR-2010

When writing code that will be in excess of three lines, please use a comment blocks. The format for such should adhere to the following standard: /** * Comments that will span multiple lines should be * placed in comment blocks such as this. The first * Line should be a forward slash with two stars, * then a newline. Commenting should not start with * the first line. Each subsequent line should be * indented with a single space, then the asterisk * and a space, followed by the text of the comment. * Each asterisk in each subsequent line should * appear in-line below the first asterisk in the * opening line of the comment. When closing the * comment block, the final asterisk should be placed * in line with the rest, followed by a forward slash * to close the block. 05-APR-2010 */

When appending to someone else's comments, add yours BELOW theirs, so that the comments read as a timeline. Only edit comments when there is a serious error of lack in the description, through this should not be a priority. If the comment is incorrect, or is no longer applicable in any part, remove it and replace it with your own. If the updated comment area will exceed three lines, convert the old comments to a comment block as described above, and append yours beginning with a new line. For example: // This is a basic comment. 05-APR-2010

Adding additional lines would then be cause for conversion: /** * This is a basic comment. 05-APR-2010 * When I wrote the comment earlier, it was just a * single line, but now I need multiple lines, so I * have converted this to a comment block. Future * comments should be appended below my comments, * which creates a log. 05-APR-2010 */

Class and Function Comments
Each Class or function should be preceded by a comment block about the class or function. Here is a typical comment block showing what the function does, the author, what args the function takes, and what it returns.

/** private function inc_num($num){ /*** increment the number ***/ return $num++; }
 * Function to increment a number
 * @author Dan Brown <-danbrown@php.net->
 * @copyright LoveMachine, LLC 2010
 * @version 0.1
 * @access private
 * @var INT The number to be incremented
 * @return INT The incremented number 05-APR-2010
 * @access private
 * @var INT The number to be incremented
 * @return INT The incremented number 05-APR-2010
 * @var INT The number to be incremented
 * @return INT The incremented number 05-APR-2010
 * @return INT The incremented number 05-APR-2010

Short tags
We don't like 'em, and neither should you. Short PHP tags are tags like <? ?>. You should not use them because they are not portable and are easily confused with xml  tags. When using PHP the correct tags are . Dont be lazy. :)

Indent and Spacing
We follow the GNU style for indenting and spacing - 4 spaces for indent, and no use of tabs. Braces style should follow as well the Java coding style and go in the same line as the declaration with a space as separator.

if (cond) { do_something; }

Line Length
As mentioned earlier, line length maximum is 120 characters, and ideally should be 75-85 chars.

Naming Guidelines What's in a name... a lot actually! We like our naming to be simple, short and easy to understand, so by looking at the name most people can grok (look it up! :P) what it means. Here are the naming guidelines for various areas:

Classes
Class definitions should use the camel case style, and use underscores for separation between package class and modules. The name of the classes should be short and self descriptive, so that by only reading the class name you would know how to use it, the same applies to the class member functions. class Communications_Mail { }

Functions
Function names should start with lowercase, and camel case style afterwards. Use common sense and write names that describe what the function does in a imperative way, for both class members or standalone functions.

class Communications_Mail {

getMailForUserID($user_id) { // Implementation }   sendEmail($to, $subject, $message) { // Implementation } } function checkSandboxMode { // Implementation }

Variables
Variable names should be simple and descriptive for improved code readability, and word separation in variables needs to use the underscore style.

e.g. Good function sendEmail($to, $subject, $message) { $utils = new Utils; $parsed_msg = $utils->parseMsg($message); }

e.g. Bad function sendEmail($to, $subject, $message) { $uClss = new Utils; $pMsg = $utils->parseMsg($message); }

Constants
Constants should be defined using uppercase words separated with underscores, and again please use descriptive names. define('SERVER_VERSION', '2.5');

Namespaces
Namespaces names should begin with an uppercase letter, and use camel case style. Use names that will easily express the purpose of the code encapsulated in them. namespace UserHelpers;

Headers
Here is an example of a file masthead, or header:

<?php /* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */ /** * ${shortdescription} * * ${longdescription} * * PHP version ${phpversion} * * LICENSE: Please see LICENSE.txt * * @category  ${category} * @package   ${package} * @author    ${user} * @copyright 2009-${year} LoveMachine, LLC * @license   Apache License (See LICENSE.txt for information.) * @version   SVN: $Id$ * @link      http://www.lovemachineinc.com/ * @see       NetOther, Net_Sample::Net_Sample * @since     File available since Release 1.0 * @deprecated N/A */ ?>

Filesystem
* Always use forward slashes (/) when referencing the filesystem. Backslashes (\) are used for escaping, but forward slashes will translate properly on Windows. * When referencing, linking, or including files, do not use ... Instead, use the dirname function. Example:  

Operating System
A few notes on creating truly portable code:

* Always use forward slashes (/) when referencing the filesystem. Backslashes (\) are used for escaping, but forward slashes will translate properly on Windows. * With the exception of email headers, please use PHP_EOL in place of \n. This will properly translate across all platforms. * Email headers - not subjects, bodies, et cetera - should always use \r\n for line endings.

Localization
Here are some rules everyone should follow to ensure maximum compatibility amongst diverse languages. For this reason, we will recommending the conversion of input text to UTF-8 before storing or handling it. At some point in the future this will change to be enforced that all string handling code adheres to this, so think ahead and start solving the issues before they appear.

* Whenever you need to do string manipulation, make sure to use UTF-8 strings so that additional characters byte length is preserved. * When using APIs or creating new ones for sending messages to the outside word (e-mail, twitter, etc.) be sure to convert the text to be send to the correct encoding. * After getting user input, always convert this text to UTF-8 using the helper functions provided (note: this helper functions don't exist yet but they will be added very soon.

Remember we will always have people from the most diverse places using our products, so let's make a great experience for them too.