Following Cake's code standards

25 June, 2007

If a team of developers follow a set of agreed code standards, it makes life a whole lot easier to compare (i.e. a diff) of two versions of the same code and see what has changed. If you try to compare two version of the exact same code formatted differently, the result will be a lot of highlighted differences when in terms of functionality they are the same. This is quite important since comparing code is the first step of integrating changes written by several developers.

You are probably thinking that this not-news is a bit obvious, and it is, but as I found myself breaking agreed code standards through the process I was using to develop, I thought it would be worth discussing ways of systematically ensuring that you follow code standards (or know that you are breaking them).

The problem part 1

What do you do if there is nothing in the code standards appropriate to what you are looking at?

Well, you trust to luck and use your best judg-(ambiguous your honor!)-ment.

In the past I did a bit of work on code quality in large development teams and at times you could clearly tell who wrote a piece of code from the style - usually this was a bad thing :). The reason was often due to the lack of guidance in the coding standards for none-trivial cases. If coding standards are well defined, who wrote the code should have little impact on how it looks.

The solution part 1

The best way to avoid ambiguity is to write well defined standards and cover some none trivial cases. If you are wondering how there can be any grey area, here are a few rules that I suggest from prior experience tweaked to (cake)php a bit:

Method names always begin with a verb and are of the form verb{AuxiliaryObject}Property
Methods are grouped within a class in this following order: admin, web accessible, protected, private
Methods are sorted alphabetically within each group (which if you follow the rest of cake's naming conventions means almost - sort methods alphabetically)
Maximum line width is 120 chars unless it's not possible to split the call or conflicts with indentation
Array values should be on one line if 3 items or less, and expanded onto multiple lines (and indented) if larger or multidimensional.
Ifs with multiple conditions, where not just local variable comparisions, should always be one condition per line
Method calls which span two lines should have the second line indented one tab more than the first.
For method calls which have too many parameters to fit on one line, consider formatting the parameters as you would an expanded array (i.e. one parameter per line).

These are examples of rules which are not covered by existing conventions.

The problem part 2

How do you ensure that your code meets code standards?

The trouble for me primarily stems from my own complacency (yes it's my fault, no question about that) and my (previous) publication process:

Write some code
Format the code with eclipse (at the time of writing my choice of editor/IDE)
commit to svn

The formatting done by eclipse takes care of indentation, line spacing of control structures and wrapping long lines. For my own work this worked out great - the code was consistently formatted meaning that comparing versions and avoiding committing purely cosmetic changes was easily achieved.

The trouble with this process is that the indentation eclipse chooses may not be what you have (ahem) agreed to follow, and it also can't take care of any other rules that you should be following. An example of what I'm talking about regarding indentation (and others if you look closely) can be seen in the patch I submitted for the tree behavior which contained many 'changes' which were purely related to indentation of parameters and comment blocks.

The solution part 2

Just write it right damn it!

Well there are a few ways to follow code standard and the first and most obvious is to write your code such that it meets all coding standards off the bat and never use any tool on your code such that it remains compliant. Here the problem is that it's too easy to be inconsistent. It also removes one of the great advantages of letting a tool indent for you; getting lost in a bunch of brackets? auto-format the code and see which one is missing/left over and correct it - job done.

Use a tool damn it!

On the other side of the equation you can write your code however you like and use some tool (not of the carbon life form verity) to format the code for you which is configured to follow your coding standards and highlight any discrepancies. The problem here is that each rule needs to be meticulously specified such that it can be applied to the source code. I had a little experience with a tool written in java which allowed you to automate reviews for code standard compliance - But what a ball ache to write the rules! I can't remember the details but in addition to needing to know what you wanted to look for there were some parameters that were specific to the tool - you needed to be an expert in it's use to actually reap any benefits from using it. Do you use a tool to format your code? If so I'd like to hear of your experiences.

The ultimate(?) solution

I have a file somewhere on my machine with a couple of regex find and replace pairs which now and again are useful to run. An example would be "find php short tags (

For many of the code standards that might be specified, a regex can be defined to check for it and therefore the ultimate solution to enforcing the majority of rules may be to write them as regexes which can then be used to either verify that some code follows the coding standards or to apply coding standards to code. For simple find and replaces definitions (php short tags, underscored variable names, white space around variable parameters, indentation) it should be possible to take someone's code, run it through a validation/correction process and out pops either a list of warnings/errors or standard compliant code or both.

So this is what I'm thinking of doing the next time I have a window of free time (scheduled for May 2010 :D)...

Wrapping up

Code standards are not the most exciting of topics, but can become a real time consumer if ignored by either an individual or a team as a whole, and it only gets worse as the team gets bigger.

Having the means to systematically either say, or even better correct where code does not meet conventions I feel would be an aid to many.

So the question remains: How do you enforce code standards in your projects?

Bake on!