Marc Gear

There have been a few blog posts floating around about a talk Tim Bray delivered at the International PHP Conference 2006. I wasn’t at the conference, nor have I heard the talk or seen slides, I’ve just read what Tobias Schlitt said about it. The other day Jeff Moore raised an interesting question – Why is PHP Code Considered Hard to Maintain?

Jeff suggests that its not PHP itself that is hard to maintain, but the programs that make it so popular, wordpress, phpMyAdmin, phpBB… those sort of things, and to a certian extent I agree. Some of the most popular php programs are a mess, and would be hard to maintain, PHP does make it easy to write code that is hard to maintain. Thats not to say it makes it hard to code ‘easy-to-maintain’ code, just that it can be easy to write sloppy PHP.

Writing maintanable code takes a degree of disipline, but it isn’t hard and it certianly has its rewards.

• Have coding standards. And stick to them. Every developer has thier own preferences, but reach a compromise with everyone on the team and agree on a set of standards that will help you keep all your code looking similar. It should be easy to scan, and will look neat. There are plenty of places to start – take a look at the PEAR standards as a starting point for your project. Dont be a nazi about your coding standards though concentrate on keeping code readable rather than strictly adhering to the standards doc.
• Organize your files. Firstly keep anything that isn’t supposed to be reached through a URL out of the webroot – templates, include files, configs, class files, log files, backups, cron scripts etc. This stuff shouldn’t be browsable. You can hide it in folders with ‘Deny from all’ directives in a .htaccess file – but its better to sit it below the webroot.Then look at your web visible file structure – put images in img/, stylesheets in styles/ and so on. Once your web visible structure is in order, then think about what you have below your webroot.Your filename conventions are also important. I normally start each class with a capital letter – so files like Template.php and Model_Abstract.class are classes, anything else is normally lowercase, underscore separated and with an extra extension if they are included files: main_header.tpl.php, global.inc.php, default_style.css default_style_print.css
• Separate your presentation logic from your page logic. Everyone says do this, but no one really explains _why_ you should do it. Separating these things allows you to re-use your presentation code elsewhere. It means your designers can play with the design _without_ ever breaking the application behind it. Remember that separation of code isn’t the same as separation of logic, for instance, alternating table row colours is presentation logic, and should be done in that layer, while checking users are logged in and have access to the specific page is page logic, and shouldn’t be done in the display layer. Savant is an excellent place to start.

• Use less code. This is obvious – the less code you write, the less you have to maintain. Re-use code wherever you can, and dont write anything you dont need. Refactor code as you go to make it as streamlined as possible. Remember to remove redundant code too.

• Documentation. Documentation. Documentation. These have got to be the three most important things to remember when it comes to maintainable code. Document your code as you write it – explain what everything does and why you’re doing it that way. This will help when you, or someone else comes to revisit the code in six months time and has to work out what it does. As a rule of thumb document anything that you can’t understand with a quick glance.You should try and comment all variable declarations, especially if the name doesn’t describe the variable too well.Each file should contain a file level docblock describing the use of the file, If a script takes _GET parameters or ARGV arguments (command line) a docblock containing a usage example should be written in the file level docblock. A usage example should be given for any classes that are not normally initiated using the constructor (eg factory classes)

  Comment on numeric data, if a number represents a length or distance, comment what units it is in (meters, miles, hours etc.)
  Comments should be used to identify missing functionality or unresolved (known) issues in the code. PHPDoc has a @todo tag specifically for this. If a block of code is commented, an explanation should be given for why it is commented, and by whom – even if it is just a temporary hack.

• Obey the OO principles you learnt at school. Encapsulate what varies, use inheritance but favour composition, depend on abstractions not concrete implementations, strive for loosly coupled objects, program to an interface not an implementation, keep classes open for extension, closed for modification yadda yadda yadda. There are enough resources online about this stuff

There you go – you have a codebase that you can come back to at any time and understand – or let a competent developer loose upon without being hugely embarrassed. \o/