WEB Advent 2011 / More Than Just Style

PHP CodeSniffer is a wonderfully simple tool for implementing and enforcing a coding standard. The basic installation comes with a handful of existing coding standards, like PEAR. One can easily cobble together a coding standard with a subset of sniffs from any of the existing coding standards. It’s even fairly simple to write your own sniffs in the event an existing sniff just isn’t quite right.

Coding standards can be controversial on many levels. Many have argued over which existing standard to use. Some have entered into arguments over which aspects to pull from multiple coding standards into a new coding standard. Others have argued over conjuring a a new coding standard which often leads to mundane arguments over where to have whitespace and how many characters per line. On the other side, there have been several that have argued that all of this arguing over what to have in a coding standard is simply wasting so much time that there could not possibly be a way that implementing and enforcing a coding standard could ever help. Assuming you can settle on a coding standard, enforcing the standard on a legacy code base can be yet another hurdle.

Many have traveled the path of choosing a coding standard and then attempted to enforce it on a legacy code base with PHP CodeSniffer with the very typical result of abandoning the whole notion of a coding standard due to the seemingly insurmountable number of errors.

The skeptics have won! There can’t be any possible benefit for spending time fixing all of these code standard violations! After all, it’s just style!

The general argument for having a coding standard is that having a common coding style will allow the programmer to focus on the problem and less on the formatting of the code.

Coding standards typically look like just style, but style can be helpful beyond reducing distractions while implementing new features. For example, disallowing superfluous whitespace can help keep your file history cleaner, as you will not have commits that only contain accidental changes to superfluous whitespace.

Coding standards are commonly referred to as style guides, but PHP CodeSniffer also has several sniffs that can save you from parse errors, like checking for duplicate property, parameter, and class names. There are other sniffs that can save you from potential runtime errors, like the sniff that detects jumbled incrementers in for loops.

There are also sniffs that can help you find where your code is complex and likely very buggy, like the nesting level and cyclomatic complexity sniffs.

Haven’t upgraded to PHP 5.3 yet? Someone has written a coding standard for that!

Not a fan of a particular language construct? You could write a sniff for that, too!

Coding standards enforced with PHP CodeSniffer can help with so much more than style, so how can we move beyond the insurmountable number of errors?

Start by picking some sniffs you would like to include in your coding standard, and see how many violations you have. If you have a small number of violations for a particular sniff, clean that up and enforce that sniff. If you find a sniffs with a large, but not too scary, number of violations, then consider distributing those across your team to fix by either by using a pre-commit hook or organizing a “fix-it” day.

Some sniffs could result in a ridiculous number of violations. This is where you will need to stop and think. Is this something worth enforcing? Did we “vote with our feet” to be doing something slightly different from this sniff? It is not a terrible thing to write your own sniff, as it is quite possible that there is some aspect of a coding standard that is already more dominate in your code than what you chose when picking out the pieces of your standard. It might be better to keep that aspect of your existing style intact rather than to modify. Also, some of the existing sniffs contain hidden subtleties that might not be for you.

From here, you should watch the number of violations for the currently unenforced sniffs go down, and eventually just fix the remainder and add those sniffs to your enforced coding standard. It may take awhile, but rest assured that your code base is becoming much better.

Developer Gift

I have two gift ideas.

I love to knit. It gives me something to do while watching my husband play video games on a frigid weekend morning, and it makes my subway commute more productive. I tried many times to knit with straight needles on my morning commute, but too often I would drop one of my needles and scramble to get it back. Then I discovered circular needles. I could now knit a hat a day, and really, who couldn’t afford to have an extra ski cap? Now, I have the Options Interchangeable Zephyr Acrylic Circular Knitting Needle Set. The acrylic tips are so light, nimble, and sharp. I am no longer dropping a needle on the train, as they are attached. An interchangeable knitting needle set is also the most cost and space efficient way to have the needle combinations needed to tackle any knitting project. You may not be a knitter (yet), but chances are you know someone who is, and it would be mighty nice of you to get them (or yourself) a set (and then ask them to make you something).

Knowing the difference between baking soda and baking powder is important, which is why I am glad there is a chapter for each in Cooking for Geeks: Real Science, Great Hacks, and Good Food. Besides, cooking is more fun when you have the know-how to make it your own, rather than programmatically executing a recipe verbatim.

Other posts