From Federico Cargnelutti

Introduction

When you have more than one developer working a project, it’s easy to waste a lot of time having people reformat each other’s code. This is clearly a waste of developer resources and time. Having a standard that everyone agrees on saves time spent reformatting and makes it much easier for one developer to pick up and understand another developer’s code.

Naming Conventions

Methods

• Method names may only contain alphanumeric characters. Underscores or numbers are not permitted.
• Method names must always start with a lower-case letter. When a method name consists of more than one word, the first letter of each new word must be capitalized. This is commonly called "camelCase" formatting.
• Use strong verbs in methods names. Methods should describe their result. The name should describe everything the routine does. Consider breaking up the routine if this is not possible.
• Methods that return boolean variables should be prefixed with is or has: isUserLoggedIn(), hasPermissionToPost().
• Use opposites: set & get, show & hide, open & close, insert & delete.

For object-oriented programming, accessors for objects should always be prefixed with either "get" or "set". When using design patterns, such as the singleton or factory patterns, the name of the method should contain the pattern name where practical to make the pattern more readily recognizable.

public function getSingleton()
{}
 
public function setSingleton(ObjectInterface $object)
{}

Variables

• Variable names may only contain alphanumeric characters. Underscores and numbers are not permitted.
• Use meaningful control variable names (not $i, $j or $k) if the function is more than a couple lines long or the loop is nested.
• Use meaningful names for temporary variables: $salesTotal instead of $nTemp.
• Boolean variable names should imply true or false. Prefix with is or has: $isLoggedIn, $hasAccess.
• Avoid names with similar meanings, that sound similar, that are different by only one or two characters, that use numerals, or are intentionally misspelled to be shorter: $hilite vs $hilight.
• Put computed qualifiers at the end of a variable name: $usersTotal, $rowsSum, $daysCount.
• A variable or type name should refer to a real world problem rather than a programming language solution, should fully and accurately describe what the variable represents and should express what, not how.
• Abbreviate consistently. Don't abbreviate to save only one character.

For class member variables that are declared with the "private" or "protected" construct, the first character of the variable name must be a single underscore. This is the only acceptable usage of an underscore in a variable name. Member variables declared "public" may never start with an underscore.

class NamingConventions
{
     private $_exampleVarA;
     public $exampleVarB;
}

Document Blocks

Every method must have a DocBlock that contains at a minimum:

• A description of the function
• All of the arguments
• All of the possible return values

/**
 * Stores an object in the registry.
 *
 * @param ObjectInterface $object
 * @return Object
 */
public function setObject(ObjectInterface $object)

Guidelines

At the small scale, coding standards documents should contain stylistic guidelines for blocks and lines of code. This typically contains rules about the use of indentation, whitespace, brace positioning, comment style, and so on.

• Indentation: Indentation is usually the hottest topic for developers to disagree over. Do you indent with space or tabs? How many spaces or how wide are the tabs? Should code fall against the left margin? How are closing braces indented?
• Whitespace: What whitespace should be included after conditional operators? Before opening braces? Between argument lists? Between binary operators?
• Braces: How are braces laid out around else statements? Can braces be omitted for simple conditional statements? Should opening braces be on the same line as the conditional that opened them?
• Comments: What kind of comment delimiters should be used? How should comments be laid out? What level of commenting is expected? How are functions introduced?
• Naming: How are variables named? How are constants named? How are functions named? How about classes?
• File layout: What should pages and templates be called? What should code libraries be named? Which folders do which files belong in?
• Line endings: Should files use DOS, Unix, or Mac line endings? Should files have UTF-8 byte order mark (BOM) sequences?

Conclusion

The key point to remember is that it’s not important that you find the best style for your code structure and layout, but rather than your application maintains a consistent style. When your style and structure is consistent, it removes the space for simple mistakes and hugely reduces the cognitive overhead involved in understanding code written by other team members.