Coding Standards – part I: File format and naming
One of the most difficult parts about understanding someone else’s code arises when their coding style follows a different set of conventions than you do, or worse, no conventions at all. To help developers approach one another’s code more easily, the most common coding conventions have been gathered by the helpful people at Zend into a set of coding standards that you can employ to help ensure that the greatest number of people will be able to easily follow your code. I’m just going to introduce you to the standards they recommend. I won’t try to cover every detail – it’s a fairly long document – but if you want to learn more than just what’s in this video, check the file included with this presentation.
The coding standards suggested by the engineers at Zend have been released to the public under the same BSD license that covers Zend Framework, which means anyone can distribute or modify it to suit their needs. However, I am supposed to keep the copyright statement with it. Very briefly, here’s their license:
{show slide ?} http://framework.zend.com/license
The first topic covered by the coding standards is file formatting. Probably the most important takeaway from this section is the fact that files containing only PHP code must not contain a closing PHP tag ‘?>’ because it could risk introducing whitespace. New programmers in PHP often don’t realize this, but you don’t need to end your PHP scripts with any tags. The only reason you should need the ‘?>’ tag is if you’re mixing non-PHP code, such as HTML, with your file. And if you do introduce whitespace, say while including a file before the headers are expected to be set, it can screw up your script’s calls to start_session, header, or set_cookie functions (among other things).
Other points in this section – use 4 spaces to indent your scripts rather than tabs (since tabs can render inconsistently across editors) and line-lengths should be limited to 80 characters as much as possible, and have an absolute limit of 120 characters. This just prevents line-wrapping from making your code hard to read. And the last thing it mentions is how lines should end with a single newline character – the ASCII character 10, hex character 0X0A. Now, I’ve set up my code editor environment to implement each of these conventions. If you use Zend Studio, here’s how I set my editor to follow these conventions:
{open text editor settings page}
I got here by going into my preferences, then selecting ‘General’, ‘Editors’, and then ‘Text Editors’. Notice I set my ‘displayed tab width’ to 4, and checked the box for ‘replace tabs with spaces’. That lets me use tabs while I code, but actually inserts spaces. And then lower down I checked the option to display print margin, and set the margin to 80 characters. It shows up as a thin gray line in my editor that I try to keep my code inside as I write it.
Last, to get the correct line ending characters, I selected the workspace menu, and switched my new text line ending character from default to ‘Unix’.
The next section in the Coding standards deals with naming conventions.
Classes should be capitalized. And the name of the class should match the name of the filepath where the class can be located, with the underscore character in place of the path separator.
So, the class ‘Report_Display_Column’ would be located in the file Report/Display/Column.php. Personally, however, I follow the convention of ending my class-containing files with ‘.class.php’. The standards used by Zend make no preference either way, so don’t feel like you need to do the same. I just think it makes it clearer for you when you’re reviewing the files I’ve included with a lesson.
Each character immediately after an underscore should also be capitalized, and there should be no cases of consecutive capital letters. So, for example, ‘Report_Display_HTML’ would be an invalid classname, but ‘Report_Display_Html’ would be fine.
Other PHP files that do not contain classes should always end in .php, and filenames may only contain alphanumeric characters, the underscore, and the dash. Spaces in filenames are singled out as being very bad.
When it comes to naming your functions and methods, they should always being with a lowercase letter, and consist of only letters and numbers. However, numbers are discouraged unless there’s a really good reason. For instance, if you think ‘html2Text’ is more readable than ‘htmlToText’.
When a function name includes more than one word, it should be written with the follow-on words capitalized. In developer-speak this is often referred to as camel-case. And verbosity is encouraged. A long function name that clearly identifies what that function does is a good thing. In the case of a class method that has been declared private or protected, its name should begin with the underscore character. And that is the only case where it is appropriate to have the underscore character in you method names. The ability to set visibility on your methods and properties is new in PHP 5, so if you’re not familiar with this, don’t worry, since it gets covered in another section of this tutorial.
As for variables and class properties, they follow the same rules as functions. Camel-case with descriptive names. Very short names like $i or $n are permitted only in the situation of very simple loop counter variables. And, as a general rule of thumb, ‘very simple’ means 20 lines or less. If your loops go longer than that, then even your loop counter variables ought to have longer names.
One other note, if a class property is declared private or protected, it should begin with an underscore, just like a private or protected class method.
The last naming convention applies to constants, and that includes class constants and constants created with the ‘define’ function. They should be named with all capital letters, and if a constant’s name consists of more than one word, the words should be separated with underscore characters. Use descriptive names to make it easier to understand what a constant is going to be used for.
February 01 2010 07:23 pm | Schmategories