DerEuroMark

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.

Note: This extends the standards of CakePHP as well as other ressources. There are some differences – especially compared to coding standards like PEAR etc.

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 intend – good php editors can transform them into spaces (as many as you find suitable). If you use spaces you cannot so easily adjust it.

['] 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="example.org" title="'.$title.'" alt="there is no alt tag" onclick="">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.

Important Definitions


CamelCase: all the words have a capital - no whitespaces
camelBack: first word has a minuscule, all following ones have a capitel

function: normal php function (for itself)
method: function INSIDE a class - usually the case in CakePHP
object: instantiated class


PHP

The { open bracket is in the same line of the function name (as shown below in the “function edit()”).
Same goes for classes, if/else statements, while-loops etc.

Objects are in CamelCase (and should represent the class name):

App::import('Core', 'File');
$FileUtil =& new FileUtil(...)

Note: After a , [Comma] there’s usually a space.

Methods and variables usually are in camelBack:

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

Note: this is not true for (prefixed) controller actions. They are actually an url link (can be accessed trough …/your_site/controller_name/method_action/…).
E.g. admin_index_all(): called per url /admin/controller/index_all/ (instead of /admin/controller/indexAll() which is not completely lowercase).

MYSQL

All tables start with a primary key (integer) called “id”, unsigned, auto-increment:

`id` int(10) unsigned NOT NULL

or (if UUIDs are used instead of AIIDs) with a char36 (char):

`id` char(36) NOT NULL

Same for the foreign keys.

The field names are lowercase – and multiple words separated through underscores:
“some_field_id” or “date_checkout”

Numeric fields (INT, TINYINT etc) can be “unsigned”, if there won’t be any negative values, primary and foreign keys must be (they can never be negative).

Usabiltity:
I started to group certain tables.
In my opinion it can be quite a difficult task to keep track of the tables belonging together (especially with using HATBM naming rule “alphabetic order”).
So I now group them by the logical “main” table. The main table will be the first word (singular! + [_]) of the other tables.

Example “role”:

roles
role_xyz (roles HasMany xyz)
role_users (HABTM between roles and users)
role_applications (HABTM between roles and users)

As you can see, here are two relations that have the same 2 tables, all of them can be found under “role…”. If you would try to sort them the cake way, you would have a naming conflict as well as (in most cases) difficulties to find them due to different first letters (roles, xyz, ..).

The naming conflict results out of the convention to have to name both “roles_users”.
Both tables have not that much to do which each other though, as the first one consists of the current roles-user-relation, the second one has some information about users applying to roles (with apply_date, approval_status (which could be -1 = dissapproved), approved_by (admin userid) and so on). But still, they all have the roles table in common. If you look for them it would not be “applications”, “applications_roles” or “xyz”, but “role_…).

Example “snippet”:

snippets
snippet_cats (snippets HasMany cats)
snippet_elements (snippets HasMany elements)
snippet_tags (HABTM between snippets and tags)

It is more logical to always group them all under the main table – in this case under “snippets”.
Otherwise you find the HATBM table for “xyzsnippets” under “tags_xyzsnippets” – but for “abcsnippets” it would be “abcsnippets_tags” – which (quite obvious) is not persuading at all.

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!),
class with underscores [_] as separator, id with minus [-]

Alternatively one could write both in camelBack style – not exactly sure what convention to follow here.

Note: ids should be unique on the current page – so don’t use them for iterating elements.

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 # for one-line comments (usually right above the code).
I do not recommend // as 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:

/**
 * @access public
 * @param string: dirty name
 * @return string: cleaned name
 * 20xx-xx-xx yz
 */
function someFunction($var) {
	...
	# now we need to shift the array as they need to be displayed in reverse order
	$var = array_shift($var);
	...
}

the last line always is [date] [2-char-abbreviation of last author]

With a good php editor (like PHPDesigner 200x), 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)

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.

Lets say we have a global css file (default site wide css) and another “specific controller” css file.
Then you could sort them like this (the action level is not really neccessary, but shows what could be done):

/***** POSTS CONTROLLER *****/
 
/*** View Action ***/
 
div.report {
	margin-left:12px;
	background-color:#E6E7E8;
}
 
/* the table for the reports */
div.report table {
	width:330px;
	border-collapse: separate;
}
div.report table td.descr {
	text-align: center;
}
...

Appendix

PHP Coding standards contains some helpful information, too (like “No Magic Numbers” etc).
Finally, the PEAR Package contains some tips about “best practices”.