Monday, March 24. 2008
Always have up to date documentation, part #2
see my previous post on the topic, #1.
My last post ended up more as a how-to than what-to. This time, I’ll say why you should have local copies of the documentation for most of the tools you use. I’ll also tell you the sort of things I always have handy as well.
Getting a local copy of php.net – and getting installed as an apache vhost and updated (probably weekly) is some effort, but well worth it. I’ve said it before, but PHP.net is the best language reference site that I’ve seen. It’s kept up to date (sometimes ahead of the code releases in fact) and while the notes that are added to it can sometimes confuse, as much as help, when they do help, they will really make the difference.
I don’t tend to buy many PHP books, because what can they do besides re-iterate what is is already there?
The most important thing to bear in mind though is not to just have the documentation there to read – you have to know what is available. Projects like PHP, the Zend Framework and PHPUnit have a lot of parts – and knowing that they have things – even if you don’t know how they work right now, can save you days or weeks of effort.
It’s for that reason that you need to at least scan over all the the docs you have – and indeed for all the libraries and tools that you use. Even I don’t read everything and expect to remember it all – but I remember enough to recognise that a paticular tool might have something to help – maybe PHP has something to search the values in an array (http://php.net/array-search), or can use Oracle, or Ldap, or Memcached, or that Zend Framework can let you easily loop over maildirs (or an mbox) to get each mail from within it. If you don’t read the manual – at least skimming over it, you would never know that functionality exists, and you inevitably end up reimplementing other people’s already debugged code. That’s a waste of your time.
So, take an hour now, and assemble a directory to put these docs into, and read through them – not everything, but at least look at headers of every section, just to get an idea of what is available and maybe go back and read up some more on things that may be useful to you. If something isn’t so interesting to you now, do bear in mind, your next project, or job, might change that.
Above all, keep learning. Never stop.
Continue reading "Always have up to date documentation, part #2"
Monday, March 17. 2008
Know thy tools first of all
Just a quick tip here, and I’ll expand on it below the cut.
When you have a library, like PEAR or Zend Framework – or ven just the whole PHP language library – it’s absolutely vital you know what it can do.
What you don’t know can cost you weeks of effort and pain. I found this out (again) today, but it’s not my pain – it’s an employee who was too busy deciding that the Zend Framework wasn’t suitable for a simple cron-script task, he has spent most of the last few weeks duplicating something that is not as good as what I could write – with ZF – in about an hour.
Tuesday, March 11. 2008
A useful idea for helping to enforce PHP code standards
extending PHP_CodeSniffer by Raphael Stolt shows how to quite easily add to a tool that will report what parts of your PHP source needs a clean-up, from the built in ‘sniffs’ for coding standards, and now adding to that for some slightly more opinionated choices on the maximum number of lines per function, or functions per class.
This could be a start of a whole collection of additional classes for additional checks.
The only challenge I see at the moment (and I don’t think it’s a big one, though I’ve not tried it, so it might not even exist, I’ve just not had the opportunity to look yet) is having to put code into the PEAR directory path, since that is where PHP_CodeSniffer is looking for the base library. I do see that they use long PEAR class-names, so it may just a matter of having the phpcs tool look elsewhere for the base coding style class.
1234.20080102 dev’). After a quick wander around the newly checked out version, maybe run a set of unit tests, just for security, it’s just as easy to put a similar ‘live’ symlink into place with a new link.
If there is ever a problem, rolling back to a previous live version is just as easy. Other configuration changes are made within the code on the apache servername, or the machine’s own hostname (more useful for CLI scripts, generally run from cron).
There are some downsides – with a complete checkout of a 40-some megabyte website (it’s mostly the Zend Framework and other libraries from which I use a number of files, though rarely all), it takes a little while (not too long, it’s a gigabit link between the repository and the main webserver) and there are also some potential caching issues (Etags are usually based on the file inodes), but as we plan to move to a multi-machine cluster – and the images aren’t being served from Apache, but a dedicated image webserver, that’s not a significant issue – and even on Apache we don’t have Etags enabled (Yslow from Yahoo also suggests that).
[edit: 18:06]
Ahah, some investigation – and copious use of echos in the phpcs script, and /usr/share/php/PHP/CodeSniffer.php class:
Creating your own standards, and using them from anywhere on the filesystem – not having to link from inside the PEAR/PHP/CodeSniffer directory:
The coding standard class with your extension:
The class is called PHP_CodeSniffer_Standards_Example_ExampleCodingStandard – the two ‘Example’s being the name of the coding standard. The file is called ‘Example/ExampleCodingStandard.php’
<?php
// in the …./Example/ directory
require_once ‘PHP/CodeSniffer/Standards/CodingStandard.php’;
class PHP_CodeSniffer_Standards_Example_ExampleCodingStandard extends PHP_CodeSniffer_Standards_CodingStandard
{
function getIncludedSniffs()
{
return array(
‘PEAR’, // the main PEAR standards
// Add our other standards, all from a subdir
dirname(FILE).‘/Standards’,
);
}
function getExcludedSniffs()
{
return array();
}
}
And in the subdir: .../Example/Standards/
– Raphael’s ToManyMethodsSniff.php and MethodLengthSniff.php files “from his post”:http://raphaelstolt.blogspot.com/2008/03/sniffing-refactoring-needs.html
To call it:
# we have to give the full path to the file called Example/ExampleCodingStandard.php
# $(pwd)/ is just Bash-ish for outputting the current directory name
phpcs —standard=$(pwd)/Example /path/to/file/to/check/ | less
Comments
Mon, 24.03.2008 19:30
Sun, 16.03.2008 23:45
Sun, 16.03.2008 21:31
Although example shown was usi ng Windows (my desktop) there is no reason why this can’t be used on Linux or as we [...]