Coding Standards

This is supposed to be a summary of guidelines addressing (web)development.
Especially if multiple team members are working on the same code – but also if one single developer wants to have clean reusable code throughout his application.

Overview

This is mainly all covered in php-fig-rectified/fig-rectified-standards coding standards.
This also extends the standards of CakePHP as well as other resources. There are some differences – especially compared to coding standards like PEAR etc.

In the past some groups arose around that very same matter. Namely FIG and phptherightway.com.
Those ideas are almost completely valid and inherited below.
There are same major and minor issues with some ideas though that cannot be accepted in the form it has been made a modern "coding standard".

The major differences (especially towards PSR-2) are outlined beforehand pretty quick:

• Tabs vs spaces: Only tabs are valid indentation.
• Consistency in {}: Opening braces always on the same line, for control structures, functions and classes

Common

The language is English, both in function/variable names and in comments.

All code lines should be indented properly – this improves readability.
Use one tab as indent – good IDEs can transform them into (soft) spaces (as many as you find suitable).

[‘] or ["]??
Usually I use the normal [‘] – as ["] is for html attributes.
No variables inside strings – they are splitted like that:

echo 'A string with '.$someVariable.' and '.SOME_CONSTANT.'!';
echo '<a href="http://example.org" title="' . $title . '">Link</a>';

This increases readability most of the time.
The other case I use ["] is inside query functions of the database object, where [‘] is needed to escape strings.

Note: The Cake Core usually puts spaces between . separated strings like $value . $value2 – you should do that this way, as well. In the past I did not always respect that, but I started to migrate my code according to the Cake conventions.

Important Definitions

CamelCase: all the words have a capital – no whitespaces

camelBack: first word has a minuscule, all following ones have a capitel

snake_case: all lowercase and separated by an underscore

function: normal php function (for itself)

method: function INSIDE a class – usually the case in CakePHP

object: instantiated class

PHP

Methods and variables usually are in camelBack:

public function xyzAbc($someVar = null) {
    ...
    return $someOtherVar;
}

Also note that methods should either be declared public or protected (never private). Same goes for class attributes.

Don’t use magic numbers (like a literal 3) directly in the code. Try to use constants for them as they are more verbose and tell the developer right away what they stand for.

HTML

All tags and attributes are lowercase.

JS

All functions are camelBack.

All style attributes have to be lowercase:

/* would not work properly: */
document.getElementById('xyz').style['Color'] = 'black';

/* it has to be: */
document.getElementById('xyz').style['color'] = 'black';

CSS

Definition:

class: .some-class-name
id: #some-id-to-an-element

both with lowercase characters (although classes are not case-sensitive, id’s are!),
the separator is minus [-]. You can use underscore [_] if it makes the separation of the identifier and the record id easier. E.g. "my-id_33". It will become necessary to do so if you use UUIDs (which contain minus chars).

Note: ids should be unique on the current page – so don’t use them for iterating elements. In general all styling should be class based. Ids are often abused for that. But
they usually serve the purpose of being identifiable via JS. So they should ideally be mainly used for dynamic JS stuff.

Do not name the fields after their style, but after the function/meaning – as the style can change and will result in things like ".red { color: yellow;}"

Good Example:

span.success {
    /* color: green; // not any more */
    color: dark-green;
}
div.important {
    /* font-weight: bold; // not any more */
    font-size: 14px;
}

Use Inheritance. And – to avoid, that any added style for other pages affect the current one, declare the inheritance the following way:

div.report {
    margin-left: 12px;
    background-color: #E6E7E8;
}
div.report table {
    width: 330px;
    border-collapse: separate;
}
div.report table th {
    font-weight: bold;
}
div.report table td.descr {
    text-align: center;
}

Now, the .descr class on the td of this table does not get screwed up, if there is any other .descr in the stylesheets.

Code Documentation

Especially inline-documentation is quite important. Not only for others, but also for yourself to be able to understand what you did some months/years ago.

All comments should in a clear way describe what is going on.

PHP:

Use /* */ for longer comments and // Some comment for one-line comments (usually right above the code).
I recommend to always add a space after // as without that space it usually stands for some line of code commented out – which can lead to misunderstandings.

You should also comment all your methods/functions – take a look at the different tags available.

Example:

/**
 * Method description here
 * 
 * @param string $var Dirty name,
 * @return string Cleaned name.
 */
public function someFunction(string $var): string {
    ...	
    // Now we need to shift the array
    $var = array_shift($var);
    ...
    return $var;
}

With a good php editor (like PHPStorm), you are able to use these method comments while programming (as it pops up on each method/function as soon as you click inside the brackets (even beyond the current page – as the editor looks through your complete app directory)

All functions/method should have @param (if applicable) and @return statements. Only constructors/deconstructors don’t have @return statements.

JS

Use /* */ for comments (usually above the code).
Although // would be allowed as well – this is (as in PHP) usually code commented out.

CSS

In CSS documents there is just the /* */ to comment your code (usually above).
You should built some kind of hierarchy with them – if you have any.

Appendix

The PEAR Package contains some tips about "best practices".