The Selling Source Programming Standard

version 1.0, 8/6/2007

By John Hargrove <john.hargrove@sellingsource.com>
The Architects <architects@sellingsource.com>

Naming Conventions

The naming conventions are fairly basic, but generally follow fairly recognizable practices that you are most likely familiar with already. Below is a breakdown of the common places you'll need to follow the standard. There may be situations not necessary listed here, but you should be able to infer them from the given examples. When in doubt, ask an architect.
Class Name MyClassName
Function/Method 
myMethodName
Function/Method Argument 
$my_argument
Private/Protected Class Variables 
$my_private_variable
Public Class Variable/Property 
$MyPublicVariable
Class/Global Constants 
MY_CONSTANT_NAME
Below is an example class following all the naming convention rules.
class MyAwesomeClass extends MyOtherAwesomeClass { const MY_CONST = 1; public $MyPublicVariable; private $my_private_variable; public function myPublicMethod($do_it) { if ($do_it) { $this->my_private_variable = 0; } } private function myPrivateMethod() { // Do stuff } }

General Structure (Parenthesis, Brackets)

Brackets are optional only in the case where the statement procedes the construct on the same line. When using brackets, they should be on the following line of the expression which precedes them. They should end on their own line as well. Additionally, spaces should separate the construct from the expression. The only case where you do not use a parenthesis with a space before it is in the case of a function or method definition, which should follow the style in the previous section.
YES
if ($something) doSomething(); while ($something) doSomething(); if ($something) { doSomething(); }
NO
// Put these on the same line, or use parenthesis to make it clear. while ($something) doSomething(); // This is the incorrect brace style. while ($something) { doSomething(); } // This is messy. Use more lines. while ($something) { doSomething(); doSomethingElse(); }

The Global Scope

A famous man once said, "The global keyword is no longer a part of your programming vocabulary." Actually, he isn't very famous. You can find him in my office. Also, I may have actually deleted the original document which contained that quote.

Procedural Code

There is almost no situation which favors procedural code over object-oriented code. At least not in PHP. Other languages may have benefits, but PHP is not one of these. If you have a defined set of functionality, then contain it in a class, not as a set of procedural functions. As our company moves forward, and our business grows, scalability and maintainability will be larger factors. OOP, in many respects, can facilitate that kind of growth.

Writing Classes

If you're using PHP 5, which you should be, you're required to take full advantage of the modern object oriented features of the language. Frequently, and to my dismay, I find developers neglecting to specify visibility or static declarations where needed, relying on one of PHP's arguably painful aspects: backward compatbility. When writing classes, ALWAYS specify whether a method or property is public, private or protected. Additionally, specify whether or not the method or variable is static. In the case of static methods, specify the static keyword after the visibility keyword. For example:
YES
class MyClass { private $my_var; public function myMethod() { } public static function myStaticMethod($my_argument) { // Do stuff } }
NO
class MyClass { function myMethod() { } }
Additionally, do not simply make methods and variable public because it is convenient and you're cutting corners. Use public sparingly. Keep in mind that public should be used as a controlled entry and exit point to an object. Exposing the vastness of a class to the outside world of the application is a breeding ground for future bugs and maintainability. This is highly important.

Type Hinting

You should make a habit of utilizing the type hinting feature in PHP. Type hinting provides a nice simple interpret-time catch for misuse of methods. While not perfect (doesn't work on primative types), it's a good way to catch wouldbe bugs. For example:
class MyClass { public function myMethod(DB_Database_1 $database) { } }
In this example, the method is difficult to misuse-- you pass a DB_Database_1 or your application has a fatal error. This useful feature can drastically improve the interoperability of a complex object heirarchy. This feature only works for arrays and objects. This is one thing you really can't do enough of. I can't imagine a situation where "too much type hinting" would ever be a problem. PHP's dynamic/loose typing is handy, but it doubles as a breeding ground for hard to track down bugs. This particular feature is one of the best ways you can help prevent those situations from ever arising. Additionally, it has the side benefit of making your code easier to understand. Winners all around.

Utilization of Core Libraries

One of the most important things to remember when developing applications at this company is to utilize the core libraries. Historically, this has been one of our greatest shortcomings. Over and over again, code has been duplicated and bugs replicated. The CVS module 'libolution' contains the latest iteration of our core libraries. The documentation for that library is located here.

Miscellaneous

There's a handful of scattered things that are a part of this standard. Some are minor, others are major. They are all brief, and listed below.