PHP Coding Standards
September 24th, 2004I have to disagree with Paul Jones on coding standards:
The thing about defining a coding style standard is that there is no objective means by which to judge one style as “better†or “more-right†than another.
I can think of several objective criteria for judging coding standards practices off the top of my head:
- Does the practice allow more code to be fit on the screen/page at one time (braces on the same line)
- Does the code use white space to emphasize when things should be separate (spaces after commas)
- Can the code written to the standard be viewed in multiple media and multiple editors (spaces not tabs, limited line lengths)
- Does the practice conserve keystrokes (tabs not spaces, no spaces after commas :))
- Does the practice facilitate copy and pasting (single statement of code per line)
- Does the practice require extra work to maintain the code (java docs and formatted comment headers are harder to edit beceause of the prefix, aligning equals signs, etc)
Obviously some practices can cause conflicts between criteria. In this case, readability should triumph over key strokes. Practices that require require editing unrelated lines during maintenance should be avoided.
One thing that I have found about refactoring is that no code smell is too small to fix. Having your code in refactored normal form and the process of getting it there by performing small, seemingly unimportant refactorings can reveal the major refactorings that are really worth it. Sometimes the major changes that need to be made are obscured by minor code smells.
Coding styles perform a similar function. Having your code in a “normalized” form frees the mind to consider other aspects of the code. Poorly or inconsistently styled code can obscure refactorings. With a good coding standard, the benefits outweigh having to re-train yourself out of a few habits. I agree with Paul’s conclusion here.
Fortunately, the PEAR standards has made the right decisions regarding these criteria with a couple of minor exceptions and many omissions.
The exceptions as I see them:
- aligning equal signs should be discouraged.
- The braces policy for functions should match that of control structures
- embedding inheritance heirarchy into the class name is bad
UPDATE: Looks I am not the only one who thinks bad style is a bad smell
All Posts
September 24th, 2004 at 1:04 pm
How dare you disagree! It’s obvious that my style is better than your style!
Not to feed the flame which I’m trying to extinguish (i.e., style wars) … but who says that, for example, “saving keystrokes” is a useful criterion? If that were the case, all variables should be named with the absolute fewest characters. This is getting into the area of “philosphical difference” — one can choose the means by which to judge the style (fewer characters, greater descriptive verbosity, whatever) and pronounce that Style A is “better” than Style B … but that’s only according to the criteria you set up. Nobody agrees on an “objective” standard which stands somehow “outside” personal preference, simply because style is itself personal preference. In the broad outlines we can agree on goals (readability, consistency, maintainability) but those are equally good for each defined style, provided you are familiar with the style.
My point, and I think we agree (as you note above) that it’s better to pick a defined style and adhere to it than to nurse your own style. This is not becaase one style is objectively “better” than another (because that’s a matter of preference), but because the social effects of having common styles is more effective in distributing workload.
Hope that clarifies what I meant by “objective” … maybe that’s not the right word for my meaning. Thanks.
September 24th, 2004 at 1:35 pm
I find the horribly counter-productive result of discussions about coding style is that they focus on trivial differences and ignoring the 99% agreement. Note that your two cents were:
- aligning equal signs should be discouraged.
- The braces policy for functions should match that of control structures
- embedding inheritance heirarchy into the class name is bad
Quite honestly, those differences would not even matter in the one area where coding standards really matter — development teams. I don’t know many teams whose productivity was effected by aligned equal sign confusion.
You and Paul both have an impact on the PHP community. I wish you would spend your time presenting and debating the best ways to implement data abstraction, or front/page controllers, or templating, or MVC, or authentication/access control, or etc. rather than this stuff.
September 24th, 2004 at 4:00 pm
I agree with most of your post; coding standards can be a huge benefit when it comes to programmer efficiency as the code formatting itself can lend context to the code.
In particular, I appreciate your comments about the PEAR standards. I have been adopting them for my own use and at work, and I find that by following a standard — any standard — I improve my own efficiency. Since PEAR is a published standard, it only makes sense to use that instead of haphazardly developing my own.
I have to disagree with two of your comments. The exceptions you have to the PEAR standards were:
I agree with point 2 completely; it irks me that the standards define the same situation differently based on context. Either put all open curly braces on their own line, or don’t. (I use VIM, and the former is actually more efficient in that editor when bouncing through it.)
However, I disagree with your other points, precisely for reasons you outlined yourself.
In point 1, I find that aligning equal signs provides a more efficient way of scanning through code — it’s easier to determine what variables are getting set to what values because I don’t have to determine where the equal sign is — all equal signs are in the same place. In addition, when editing, it becomes trivial to select a block including the variable names and equal signs in order to transform that block (for instance, to create an array of values instead of many variable assignations). (Those familiar with VIM and its visual blocks will know what I’m speaking about.)
In point 3, again, I find that naming classes as PEAR suggests is efficient — I can tell from the class name where in the directory hierarchy to find the class’ file. It also makes it easy to build __autoload() functions that utilize the classname to find the file containing the class — change underscores to directory separators, and you’re done.
As this post testifies — there can be many reasons to adopt one standard over another, and debate will continue after the standard is set. However, the real debate is more a matter of determining what standard you will use than debating all the points about them. I would certainly favor changing how opening curly braces are done in PEAR — but unless the PEAR standards change, I’ll do as they outline so that I’m following a known standard — which will make my coding style predictable to other programmers — and hopefully help them be more efficient when modifying my code.
October 5th, 2004 at 6:09 pm
I think most people miss the point regarding standards in general; i.e. to improve readability and therefore the ability to maintain code.
April 13th, 2007 at 9:12 am
Problem for me is as well, that my fellow colleagues don’t like coding standards or coding practices like written about here or on http://php-coding-practices.com
I still find coding standards to be a very good idea.
I fully second Ignatius.