Thursday, 5 May 2011

Did Moodle not get the memo?

I cannot tell you how many programming books I have read which drill in the importance of documentation.  Of course documentation is not always perfect, but I genuinely thought that every programmer realised it was vital to the health of a project that the documentation is as good as possible.

Reading this sentence though suggests the Moodle development team have been reading a different set of books to me:-
Normally, if you want a particular sort of setting, the easiest way is to look around the admin screens of your Moodle site, and find a setting like the one you want. Then go and copy the code and edit it. Therefore, we do not include a complete list of setting types here. Moodle.org
It is perhaps stranger still to me that the most important set of documentation the How to create a Moodle Block is still not up to date with the current version!  Luckily is you spend enough time looking around in the PHP code you can find the information you want, but this should not be the preferred method as the above code suggests.

Copying code without understanding is simply bad, you will introduce bugs and inefficiency copying over redundant or incorrect code accidentally re-use variables etc and break an application in an unexpected manner.  Copying code and referring back to the documentation about the code is much better as it allows you to appreciate what the code is doing in its entirety and perhaps identify bugs and inefficiencies from first principles.

Now as a developer I understand the need to work on the next feature or fix a bug is great, but Open Source only works as a model because of 3rd party contribution, without good documentation 3rd part contribution is significantly harder and open source's main advantage is massively eroded.  Going through the source is a great benefit, but should never be the first port of call for a 3rd party developer.

No comments: