Bad, untidy, ugly, messy code is one of my pet hates. This is by no means a definitive post, but a few guidelines on how to instantly make code less ugly and more maintainable. Please don’t think that by applying these 5 steps that your code will instantly be maintainable, however it would be a good place to start!
1. indent your code
If I open up some code and its not properly indented, I have to wade through the code and indent it correctly. It honestly makes it soo much easier to read and make changes to, if everything is indented properly. Sometimes I wish PHP was like Python and absolutely required code to be indented properly.
I cannot stress this enough, indent your code!
2. name variables meaningfully (but sensibly)
Another one of my pet hates. Variable names like the following…
$mv = 'blah';
I would much rather have to spend an extra few seconds writing a longer variable name which makes sense, so in our example above, something like…
$my_variable = 'blah';
Now, this also requires some common sense. Yes longer variable names are good if it makes them more meaningful, but that doesn’t mean you should go overboard, for example…
$this_is_my_variable_name_right_here_long_and_meaningful = 'blah';
…is just taking it a bit too far.
Meaningful variable names should also be used in the database. For example TABLENAME_id is far better than simply id.
3. comment your code
There is no such thing as ’self documenting’ code. Sure you can write some code which is really obvious what it does, but if there’s any doubt what so ever, even a smidgin…write a frickin comment.
It will take only a few seconds extra and could save the next developer hours.
There is also no such thing as over-commenting, although quality should always trump quantity.
Also worth mentioning is docblocks, these are excellent and means you can use a documentation tool such as phpDocumentor to create documentation for your code.
4. use a coding standard
Coding standards make life so much easier, especially when developing in a team. They set the development rules. Without rules, anarchy ensues, and the same goes for code. I hate to have to open some code and see something like the following where different developers have added or edited the code…
require_once 'blah.php';
include("foobar.php");
if ($foo == $bar) {
$random_array[] = 'hello';
}
foreach ($random_array as $word)
{
echo "hello";
}
Using a coding standard you would not get the mixture of bracket placement, the single and double quotation mash-up and you wouldn’t get the combo of require_once and include().
There are a few coding standards out there, but the one I would go for is the PEAR standard.
5. separate code and html
I’m not going to get into a spiel about MVC (I’ll save that for another post) but what you should definately have is a clear separation between your code and your html. Even if this means just having your code at the top of the page and the html at the bottom, it’s a start. However, ideally you should be putting your html is a separate file, bonus marks for using a templating engine.
