Development hints and tips

Note: This page is a work-in-progress. Feedback and suggested improvements are welcome. Please join the discussion on moodle.org or use the page comments.

There is a great deal of development experience amongst the Moodle developers. This page is some general hints and tips that may help people starting out in PHP and Moodle development.

Follow the Coding Guidelines

Moodle has a well developed set of Coding Guidelines. Read them and follow them. It's surprising how many custom plugins for Moodle do not. It instantly prevents your code from being incorporated in core Moodle.

Use a Version Control system

If you are developing without a version control system then you are doing it wrong. The benefits run well beyond just being able to keep past versions of your code. Moodle currently uses CVS for core development but this is probably a poor (out of date) choice for a new project. The world seems to be moving towards Git. This is a powerful distributed system and does take a bit of getting your head around but the effort is worth it.

Find an editor or IDE that works for you and learn it properly

There are many different development platforms from complex Integrated Development Environments (IDEs) to simple editors and command line tools. Choose something that works for you and then take the trouble to learn how to use it properly.

Comment effectively

Don't be shy about putting comments in code. If the code deserves a blank line it probably deserves a comment. It's obvious what the code does now but it won't be in six months.

Use good variable and function names

It should be easy and obvious to pick a name for a variable or a function. If it isn't you are either trying to make that function too complicated (simplify and break it up) or you haven't full understood what you are trying to do (another cup of coffee?). Names should always say what they are for or what they do - plainly.

Pretty code is good code

Seriously! Code that is well laid out and easy to read is easy to debug and to modify. Make the effort to lay out code so it looks good and is easy to read through. Don't be afraid to break something nasty into several lines so that it reads well. It's tempting to make one line of code do something incredibly complex but you won't feel so clever when you can't remember how it works.

Write Plugins. Use APIs

Always, when developing custom features, write a standard plugin rather than modifying core code. Even if you have to compromise the functionality a bit. Most Moodle plugin structures are able to easily create database structures, handle role capabilities, define language files and ease future updates. Furthermore, the end result can all be delivered in one simple zip file. It doesn't rely on one particular build of Moodle either. These are real and big advantages. A core code patch is only guaranteed to work with the exact build it was written with, it probably won't survive upgrades and patches are notoriously difficult to apply properly - even for experienced developers. If in doubt look at blocks - you can do an awful lot with a block (even if it's never actually added as a visible block). Blocks are reasonably easy to understand and to develop, too.

Similarly, take the trouble to investigate existing Moodle APIs and library calls. Your code will last longer and be more reliable.

Don't Make Me Think

It's actually a title of a book by Steve Krug (and it should be obligatory reading for all web designers), however, the point is really about Usability. Usability is hard but you still have to try. Don't make your users have to think. Good documentation is important but it's hard to keep it up to date and it's a partial failure if someone has to resort to reading it. In particular, be quite clear that ordinary Moodle users don't care about clever implementation or super flexibility. Anything that complicates the job of getting effective learning materials to students is "a bad thing". Anything that in the name of adding flexibility or functionality makes an ordinary user's job more complex is a regression. If something must be done then the code must do it - do not burden the user.

It should be hard (or even better impossible) for users to break things. The greatest invention ever was the undo button - it doesn't only protect the user against mistakes it allows them to safely experiment. Users don't learn to use software by reading the manual - they experiment and guess. Make it easy for them.

More tips please

(add your own!)