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.

Avoid writing code in the first place

Always take the trouble to find if there is another (existing) way to do what you need. Failing that, does a plugin or option already exist. Failing that, does something exist that you can modify. Failing that, is there a library (or libraries) that exist to reduce your effort. Lastly write the code yourself. Existing, tested code is always to be preferred - more so if it has an extensive user base.

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.

When in Rome, do like the Romans

The Coding Guidelines do not describe every possible situation. When you find yourself in that situation, try to follow the example of how things are done in other parts of Moodle. Just because Moodle is not written the way you would do it if you were starting from scratch does not matter. In a large project like Moodle, it is more important to keep the code consist than it is to satisfy your personal prejudices about how code should be. That makes it easier to maintain the code, and if you start writing Moodle-style code, you will find it easier to understand the other bits of Moodle code you look at.

Of course, some parts of Moodle are just badly written. You should not copy what is done in those places. ;-) When looking for examples to follow, try to find code that has been written recently by one of the reliable core developers.

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 fully 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.

Separate out functionality

Or... don't muddle up the user interface with the database access and other logic. For example, alarm bells should ring if you are writing functions like get_data_and_display(). It is a much better idea to write get_data() and then display_data(). The effort is little or no different, however, the end result is often easier to follow and (say) if someone asks you to dump the data to Excel rather than display it the latter method saves you a costly refactor. Even if you are not writing functions and your logic is all on one page try to split things into logic blocks - read the input, THEN do the calculations and database access, THEN display the output. It will be easier to refactor or to modify.

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.

There's some guidelines (currently under development) in User Interface Guidelines

More tips please

(add your own!)