Development hints and tips - Revision history

Deraadt: Updating links to User docs

2011-09-21T06:51:03Z

Updating links to User docs

← Older revision		Revision as of 06:51, 21 September 2011
Line 89:		Line 89:
	== Turn on Debugging and fix those notices and warnings ==		== Turn on Debugging and fix those notices and warnings ==

	If you get PHP warnings or notices when [[Debugging]] is switched on the problem is '''not''' that debugging has been left on, the problem is that there are bugs in your code. There is no excuse for not checking for and then fixing notices and warnings. To not do so is shoddy at best.		If you get PHP warnings or notices when [[:en:Debugging\|Debugging]] is switched on the problem is '''not''' that debugging has been left on, the problem is that there are bugs in your code. There is no excuse for not checking for and then fixing notices and warnings. To not do so is shoddy at best.

	== Expand Moodle Docs ==		== Expand Moodle Docs ==

Howardsmiller: /* Use a Version Control system */

2011-02-04T10:36:20Z

Use a Version Control system

← Older revision		Revision as of 10:36, 4 February 2011
Line 23:		Line 23:
	== Use a Version Control system ==		== 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~~. Moodle uses [[Git tips\|Git]] for developing so it makes sense to learn it. This is a powerful distributed system and does take a bit of getting your head around but the effort is worth it.		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 uses [[Git tips\|Git]] for developing so it makes sense to learn it. 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 ==		== Find an editor or IDE that works for you and learn it properly ==

Howardsmiller: /* Generate helpful error messages */

2011-01-30T20:51:50Z

Generate helpful error messages

← Older revision		Revision as of 20:51, 30 January 2011
Line 82:		Line 82:

	Never write an error message that looks something like "An unknown error occurred". You might as well not bother as this doesn't help anybody fix the problem.		Never write an error message that looks something like "An unknown error occurred". You might as well not bother as this doesn't help anybody fix the problem.

			== Don't make empty pages and blocks ==

			If you write code that returns (typically) a block (but you can do it lots of places) think very carefully before returning nothing. An empty return for a block causes the block not to be displayed at all. Unless you have a very compelling reason to do this avoid it. It will confuse the user - they add a block and then nothing happens. If some capability or configuration is required consider displaying a message to help them. In a report or other pages that return variable data, be careful how you deal with empty data sets. Always display something like "no data found" rather than a blank page. Blank pages make users think something is broken.

	== Turn on Debugging and fix those notices and warnings ==		== Turn on Debugging and fix those notices and warnings ==

Howardsmiller: /* Use a Version Control system */

2010-12-23T09:56:14Z

Use a Version Control system

← Older revision		Revision as of 09:56, 23 December 2010
Line 23:		Line 23:
	== Use a Version Control system ==		== 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. Moodle ~~will soon be using~~ [[Git tips\|Git]]. This is a powerful distributed system and does take a bit of getting your head around but the effort is worth it.		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. Moodle uses [[Git tips\|Git]] for developing so it makes sense to learn it. 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 ==		== Find an editor or IDE that works for you and learn it properly ==

Howardsmiller: /* Generate helpful error messages */

2010-12-23T09:52:14Z

Generate helpful error messages

← Older revision		Revision as of 09:52, 23 December 2010
Line 80:		Line 80:

	Add extra debugging code (call ''debugging()'' )if you think it might help. This is especially true for functions that have complex configuration or external dependencies (i.e. lots that can go wrong).		Add extra debugging code (call ''debugging()'' )if you think it might help. This is especially true for functions that have complex configuration or external dependencies (i.e. lots that can go wrong).

			Never write an error message that looks something like "An unknown error occurred". You might as well not bother as this doesn't help anybody fix the problem.

	== Turn on Debugging and fix those notices and warnings ==		== Turn on Debugging and fix those notices and warnings ==

Howardsmiller: /* Generate helpful error messages */

2010-12-23T09:50:41Z

Generate helpful error messages

← Older revision		Revision as of 09:50, 23 December 2010
Line 80:		Line 80:

	Add extra debugging code (call ''debugging()'' )if you think it might help. This is especially true for functions that have complex configuration or external dependencies (i.e. lots that can go wrong).		Add extra debugging code (call ''debugging()'' )if you think it might help. This is especially true for functions that have complex configuration or external dependencies (i.e. lots that can go wrong).

			== Turn on Debugging and fix those notices and warnings ==

			If you get PHP warnings or notices when [[Debugging]] is switched on the problem is '''not''' that debugging has been left on, the problem is that there are bugs in your code. There is no excuse for not checking for and then fixing notices and warnings. To not do so is shoddy at best.

	== Expand Moodle Docs ==		== Expand Moodle Docs ==

Howardsmiller: /* Use a Version Control system */

2010-12-05T19:43:40Z

Use a Version Control system

← Older revision		Revision as of 19:43, 5 December 2010
Line 23:		Line 23:
	== Use a Version Control system ==		== 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 tips\|Git]]. This is a powerful distributed system and does take a bit of getting your head around but the effort is worth it.		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. Moodle will soon be using [[Git tips\|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 ==		== Find an editor or IDE that works for you and learn it properly ==

Howardsmiller: /* Write Plugins. Use APIs */

2010-07-30T10:47:58Z

Write Plugins. Use APIs

← Older revision		Revision as of 10:47, 30 July 2010
Line 49:		Line 49:
	== Write Plugins. Use APIs ==		== 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.		Always, when developing custom features, write a standard plugin in preference to 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.		Similarly, take the trouble to investigate existing Moodle APIs and library calls. Your code will last longer and be more reliable.

Howardsmiller: /* Generate helpful error messages */

2010-07-27T14:48:31Z

Generate helpful error messages

← Older revision		Revision as of 14:48, 27 July 2010
Line 78:		Line 78:

	You should also try to trap as many possible errors as possible. If a function returns a fail condition then you would need to have a very good reason not to check it. This helps avoid the highly unpopular "white screen of death".		You should also try to trap as many possible errors as possible. If a function returns a fail condition then you would need to have a very good reason not to check it. This helps avoid the highly unpopular "white screen of death".

			Add extra debugging code (call ''debugging()'' )if you think it might help. This is especially true for functions that have complex configuration or external dependencies (i.e. lots that can go wrong).

	== Expand Moodle Docs ==		== Expand Moodle Docs ==

Howardsmiller: /* KISS (Keep It Simple Stupid) */

2010-07-25T08:53:07Z

KISS (Keep It Simple Stupid)

← Older revision		Revision as of 08:53, 25 July 2010
Line 37:		Line 37:
	== KISS (Keep It Simple Stupid) ==		== KISS (Keep It Simple Stupid) ==

	Albert Einstein didn't ''actually'' say "Everything should be made as simple as possible, but no simpler" but it would still have been good advice if he had. Take the trouble to come up with the simplest solution to the problem at hand. Resist the temptation to add code for things that you ''might'' need in the future or ''might'' be required one day. They usually never happen and you can always change the code later if requirements change. ~~Don~~'t use some insanely complex object factory when old-fashioned procedural programming will do. Don't use old-fashioned procedural programming when a class-hierarchy models the real-world problem more intuitively. Avoid complex abstractions where they are not actually needed to get the job done. Any additional code increases the risk of bugs, security problems and maintenance issues in the future.		Albert Einstein didn't ''actually'' say "Everything should be made as simple as possible, but no simpler" but it would still have been good advice if he had. Take the trouble to come up with the simplest solution to the problem at hand. Resist the temptation to add code for things that you ''might'' need in the future or ''might'' be required one day. They usually never happen and you can always change the code later if requirements change. For example, don't use some insanely complex object factory when old-fashioned procedural programming will do. Don't use old-fashioned procedural programming when a class-hierarchy models the real-world problem more intuitively. Avoid complex abstractions where they are not actually needed to get the job done. Any additional code increases the risk of bugs, security problems and maintenance issues in the future.

	== Use good variable and function names ==		== Use good variable and function names ==