Archive for April 18, 2006

I have determined this day to blog about a topic which is sorely missing in at least half the PHP (and other!) projects I have reviewed over the space of the last year. I say a period of a year, but you can drag it back in time.

My first presumption is that all people have at least a working knowledge of their native language (questionable I know ). Languages are weird things, often full of obscure rules which may not only differ between related languages – but between dialects also. However they all generally have similar standard rules, terms, and conventions.

Programming is a language. Most people tend to agree with that statement. Afterall how many would interpret:

if($i == 2){
echo ‘True’, “\n”;
}

as:

If variable i equals 2 then echo True-newline.

Most people would be my guess. The if statement is one of the most common constructs in programming today – even BASIC on the Commodore 64 I vaguely remember playing Dizzy (horrible thought…) used it. Unfortunately there is an enemy of language. This enemy is a crafty nefarious beast who slithers across text editors and IDE’s across the world whispering madness. You will recognise this creatures foul deeds when you happen across something like

if($i == 2)
echo ‘True’, “\n”;
$i = 3;
echo $i, “\n”;

This is something horrific which should immediately be banished to the Netherworlds from whence it crawled.

But there is worse. Much worse. There are horrors whose malevolence may drive you insane, tearing hair from your head and leaving you slumped on your keyboard moaning in fear… There are developers who may resist so much as a suggestion of a flaw…

Therefore I have collated the following rules (dutifully plagiarising some in the blogosphere tradition):

1. A programming language is like any language; use full sentences with correct grammer. Please…

2. An if statement without braces (curly brackets if you’re confused) is an if statement capable of unimaginable evil. Brevity is not an excuse for laziness. And yes, it is lazy.

3. Remember that short tags, asp tags or any other alternative are also evil. Only the most depraved would dare use them. Use

4. Register globals cannot be ignored. In short, don’t rely on them. If you do you shall be punished in unspeakable ways by people whose server leaves it off as a security precaution.

5. If you decide to comment code, than use full sentences. phpDoc generation makes no sense unless comments actually explain the code – not simply summarise it as “My DoThis() function”. All those funny @return, @param and such tags are essential – they’re not optional.

6. depreciated != deprecated

7. Do not mix functions or object methods which do the same thing. It’s annoying, confusing and makes Maugrim a little crazy. Likewise do not mix using a getter/setter with directly accessing a class property – its just as bad.

8. Indent code appropriately. It makes reviewing code a simpler faster process.

9. Always update 3rd party code as required, i.e. whenever the 3rd party releases an update.

10. Never ignore constructive criticism – it’s officially termed “peer review” and considered a good thing.

11. When someone tells you your code contains a security vulnerability, please – do not ignore it for 6 months until someone with access to a major security listing decides to give it a lot of publicity. It’s a bit rude.

12. Never claim you are separating PHP from HTML in an application… Because that’s plain stupid.

I give these in no particularly order, and in no particular category. They are just some things I most often find annoying me when trying to read or adapt code. Some annoy because what they claim to do may differ from what they actually do – particularly annoying when its pointed out and they refuse to update documentation.

Nearly all of these I view as common sense. I’m not above admitting my common sense may differ from someone elses. But from a personal point of view the above 12 points usually capture most things which frequently annoy me when reading someone’s source code.