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.

Comments

Post a Comment

Popular posts from this blog

IE9 Intranet compatibility mode in Intranet websites

So you have written an HTML5 site on your local intranet with some lovely CCS3 and run it up in Firefox and you feel smug, all your HTML and CSS are perfectly formed, but you run it up in IE9 and all the CSS3 goodness has gone away leaving your lack luster IE7 version of your site.   Why is IE9 running in IE7 compatibility mode? IE9 has a hidden setting that forces it to run in compatibility mode when it encounters any intranet websites. Microsoft have detailed this behaviour in a Blog about what they call Smart compatibility mode . You can easily switch off the compatibility mode for specific machines using the internet tools mentioned in the article above, but most of the time developers do not have the luxury of applying corporate wide settings of this nature. Avoiding Smart compatibility with X-UA-Compatible Luckily there is a single line of HTML you can that you can use to override this behaviour: <meta http-equiv="X-UA-Compatible" content="IE=edge,c
Read more

User Interface Usability Checklist Part 2

So you made it through part 1 of the usability check list, how about part 2? 21. Poor Label Alignment If you have been through design 101 you have probably heard of the wonderful acronym for the basic principles of design, C.R.A.P. This of course stands for Contrast, Repetition, Alignment and Proximity. Proximity is very important when identifying which label belongs to which input. Each different form of alignment has its advantages and disadvantages. Left Alignment The label appearing on the left of a box is a common practice. This often helps with vertical space and keeping all of the elements of a form on a single page, which can be beneficial in aiding the user in form completion and making them aware of all of the possible options they can, or made need to provide information for. It does however have a few disadvantages. Long labels cause short label's input boxes to be far away from the end of the label, this damages that basic principle of proximity. In extreme
Read more

Procedural VS Object Oriented

What is the correct way to write code? If you have worked with PHP long enough you may well have come across the website  PHP The Right Way . This website is dedicated to helping developers learn the industry best practices. Interestingly another site appeared afterwards called  PHP The Wrong Way . In essence this website is a rebuttal to the many of the recommendations made in PHP The Right Way. With any sphere of learning it is important to keep an open mind, to listen and critically evaluate the received wisdom and determine if it is indeed wisdom or opinion built on shaky ground. There is one part of the argument I would like to focus on and this is the argument for and against " Always use object-oriented Programming ". While PHP The Right Way does not appear to explicitly state that you should always use an object oriented approach it is implicit from the examples and the recommendations to use design patterns. While there are programming approaches available othe
Read more