Development:Coding - Revision history

Tsala: {{Template:CategoryAdministrator}}

2011-03-17T19:18:36Z

← Older revision		Revision as of 19:18, 17 March 2011
Line 1:		Line 1:
			{{Template:CategoryAdministrator}}

	Any collaborative project needs consistency and stability to stay strong.		Any collaborative project needs consistency and stability to stay strong.

Skodak: /* General rules */

2008-11-27T22:38:34Z

General rules

← Older revision		Revision as of 22:38, 27 November 2008
Line 12:		Line 12:
	# Each file should '''include (require_once) the main config.php''' file.		# Each file should '''include (require_once) the main config.php''' file.
	# Any '''other include/require should use an absolute path''' beginning with $CFG->dirroot or $CFG->libdir, not relative includes, which [http://uk.php.net/manual/en/function.include.php sometimes behave strangely under PHP].		# Any '''other include/require should use an absolute path''' beginning with $CFG->dirroot or $CFG->libdir, not relative includes, which [http://uk.php.net/manual/en/function.include.php sometimes behave strangely under PHP].
			# Includes should be done at the top of files or inside functions/methods, do not include/require in the middle of file in global scope
	# Each file should '''check that the user is authenticated correctly''', using require_login() and has_capability() or require_capability().		# Each file should '''check that the user is authenticated correctly''', using require_login() and has_capability() or require_capability().
	# All '''access to databases should use the functions in ''lib/dmllib.php''''' whenever possible - this allows compatibility across a wide range of databases. You should find that almost anything is possible using these functions. If you must write SQL code then make sure it is: cross-platform; restricted to specific functions within your code (usually a lib.php file); and clearly marked.		# All '''access to databases should use the functions in ''lib/dmllib.php''''' whenever possible - this allows compatibility across a wide range of databases. You should find that almost anything is possible using these functions. If you must write SQL code then make sure it is: cross-platform; restricted to specific functions within your code (usually a lib.php file); and clearly marked.

Garrettn: /* Database structures */ Typo fix and rewording for clarity

2008-11-10T23:04:43Z

Database structures: Typo fix and rewording for clarity

← Older revision		Revision as of 23:04, 10 November 2008
Line 141:		Line 141:
	#* name - the full name of each instance of the module		#* name - the full name of each instance of the module
	# Other tables associated with a module that contain information about 'things' should be named widget_things (note the plural).		# Other tables associated with a module that contain information about 'things' should be named widget_things (note the plural).
	# Table and column names should avoid using [[Database reserved words\|reserved words in any database]]. Please check them before creation. Table names ~~must at most~~ 28 characters long. Column names ~~at most~~ 30 characters.		# Table and column names should avoid using [[Database reserved words\|reserved words in any database]]. Please check them before creation. Table names may be up to 28 characters long, and Column names up to 30 characters.
	# Column names should be always lowercase, simple and short, following the same rules as for variable names.		# Column names should be always lowercase, simple and short, following the same rules as for variable names.
	# Where possible, columns that contain a reference to the id field of another table (eg widget) should be called widgetid. (Note that this convention is newish and not followed in some older tables)		# Where possible, columns that contain a reference to the id field of another table (eg widget) should be called widgetid. (Note that this convention is newish and not followed in some older tables)

TimHunt at 10:54, 19 September 2008

2008-09-19T10:54:03Z

← Older revision		Revision as of 10:54, 19 September 2008
Line 178:		Line 178:
	# Blocks of code to be included should contain a definite PHP structure (e.g, a class declaration, function definition(s) etc.) - straight blocks of code promote uninitialised variable usage.		# Blocks of code to be included should contain a definite PHP structure (e.g, a class declaration, function definition(s) etc.) - straight blocks of code promote uninitialised variable usage.
	# If you need to use shell_exec() (or any other shell invoking function), make sure you clean parameters first with escapeshellcmd()/escapeshellarg (otherwise, we open up for shell injection attacks).		# If you need to use shell_exec() (or any other shell invoking function), make sure you clean parameters first with escapeshellcmd()/escapeshellarg (otherwise, we open up for shell injection attacks).

			==Use of JavaScript within Moodle==

			On a separate page, see [[Development:JavaScript guidelines]].

	[[Category:Developer\|Coding]]		[[Category:Developer\|Coding]]

TimHunt: /* Database structures */

2008-09-02T02:52:36Z

Database structures

← Older revision		Revision as of 02:52, 2 September 2008
Line 141:		Line 141:
	#* name - the full name of each instance of the module		#* name - the full name of each instance of the module
	# Other tables associated with a module that contain information about 'things' should be named widget_things (note the plural).		# Other tables associated with a module that contain information about 'things' should be named widget_things (note the plural).
	# Table and column names should avoid using [[Database reserved words\|reserved words in any database]]. Please check them before creation.		# Table and column names should avoid using [[Database reserved words\|reserved words in any database]]. Please check them before creation. Table names must at most 28 characters long. Column names at most 30 characters.
	# Column names should be always lowercase, simple and short, following the same rules as for variable names.		# Column names should be always lowercase, simple and short, following the same rules as for variable names.
	# Where possible, columns that contain a reference to the id field of another table (eg widget) should be called widgetid. (Note that this convention is newish and not followed in some older tables)		# Where possible, columns that contain a reference to the id field of another table (eg widget) should be called widgetid. (Note that this convention is newish and not followed in some older tables)

Jrogerswti: /* General rules */ added emphasis for most important parts of the rules. KISS

2008-07-02T21:43:01Z

General rules: added emphasis for most important parts of the rules. KISS

Skodak: /* Security issues (and handling form and URL data) */

2008-06-06T14:02:08Z

Security issues (and handling form and URL data)

← Older revision		Revision as of 14:02, 6 June 2008
Line 170:		Line 170:
	# All filenames must be 'cleaned' using the clean_filename() function, if this has not been done already by appropriate use of required_param() or optional_param()		# All filenames must be 'cleaned' using the clean_filename() function, if this has not been done already by appropriate use of required_param() or optional_param()
	# Any data read from the database must have [[Developer:Slashes\|addslashes()]] applied to it before it can be written back. A whole object of data can be hit at once with addslashes_object().		# Any data read from the database must have [[Developer:Slashes\|addslashes()]] applied to it before it can be written back. A whole object of data can be hit at once with addslashes_object().
			# addslashes_js() must be used for escaping of javascript strings
	# Wherever possible, data to be stored in the database must come from POST data (from a form with method="POST") as opposed to GET data (ie, data from the URL line).		# Wherever possible, data to be stored in the database must come from POST data (from a form with method="POST") as opposed to GET data (ie, data from the URL line).
	# Do not use data from $_SERVER if you can avoid it. This has portability issues.		# Do not use data from $_SERVER if you can avoid it. This has portability issues.

Skodak: /* General rules */

2008-05-30T15:39:26Z

General rules

← Older revision		Revision as of 15:39, 30 May 2008
Line 27:		Line 27:
	# When generating a HTML link, always make it relative to the full site root, i.e. link to ''$CFG->wwwroot/mod/blonk/view.php?id=99'' rather than just ''view.php?id=99''. This means that your code will work if called by a script in another folder, among other things.		# When generating a HTML link, always make it relative to the full site root, i.e. link to ''$CFG->wwwroot/mod/blonk/view.php?id=99'' rather than just ''view.php?id=99''. This means that your code will work if called by a script in another folder, among other things.
	# Modules should store their config variables using ''set_config('varname', $value, 'mod/modulename')'' where the last parameter is the path to the module directory.		# Modules should store their config variables using ''set_config('varname', $value, 'mod/modulename')'' where the last parameter is the path to the module directory.
			# Respect decimal separators specified in language pack - do not use number_format() directly, instead use format_float() and unformat_float() when displaying or processing floating point numbers (mandatory in 2.0)

	==Coding style==		==Coding style==

Rubenback26 at 17:59, 17 May 2008

2008-05-17T17:59:37Z

← Older revision		Revision as of 17:59, 17 May 2008
Line 183:		Line 183:
	[[zh:代码指南]]		[[zh:代码指南]]
	[[pl:Kodowanie]]		[[pl:Kodowanie]]
			[[pt:manual_de_codigo]]

Mudrd8mz: /* Coding style */ naming classes and their methods

2008-05-11T19:29:18Z

Coding style: naming classes and their methods

@@ Line 59: / Line 59: @@
+           }
+       }
 . Blocks must always be enclosed in curly braces (even if there is only one line). Moodle uses this style:

← Older revision		Revision as of 21:43, 2 July 2008
Line 5:		Line 5:
	==General rules==		==General rules==

	# All code files should use the .php extension.		# All '''code''' files should use the '''.php''' extension.
	# All template files should use the .html extension.		# All '''template''' files should use the '''.html''' extension.
	# All text files should use Unix-style text format (most text editors have this as an option).		# All text files should use '''Unix-style text format''' (most text editors have this as an option).
	# All php tags must be 'full' tags like <?php ?> ... not 'short' tags like <? ?>.		# All php tags must be 'full' tags like '''<?php ?>''' ... not 'short' tags like <? ?>.
	# All existing copyright notices must be retained. You can add your own if necessary.		# All existing '''copyright notices must be retained'''. You can add your own if necessary.
	# Each file should include (require_once) the main config.php file.		# Each file should '''include (require_once) the main config.php''' file.
	# Any other include/require should use an absolute path beginning with $CFG->dirroot or $CFG->libdir, not relative includes, which [http://uk.php.net/manual/en/function.include.php sometimes behave strangely under PHP].		# Any '''other include/require should use an absolute path''' beginning with $CFG->dirroot or $CFG->libdir, not relative includes, which [http://uk.php.net/manual/en/function.include.php sometimes behave strangely under PHP].
	# Each file should check that the user is authenticated correctly, using require_login() and has_capability() or require_capability().		# Each file should '''check that the user is authenticated correctly''', using require_login() and has_capability() or require_capability().
	# All access to databases should use the functions in ''lib/dmllib.php'' whenever possible - this allows compatibility across a wide range of databases. You should find that almost anything is possible using these functions. If you must write SQL code then make sure it is: cross-platform; restricted to specific functions within your code (usually a lib.php file); and clearly marked.		# All '''access to databases should use the functions in ''lib/dmllib.php''''' whenever possible - this allows compatibility across a wide range of databases. You should find that almost anything is possible using these functions. If you must write SQL code then make sure it is: cross-platform; restricted to specific functions within your code (usually a lib.php file); and clearly marked.
	# Don't create ~~or use~~ global variables ~~except for~~ the standard $CFG, $SESSION, $THEME, $SITE, $COURSE and $USER.		# '''Don't create new global variables'''. Use only the Moodle-standard $CFG, $SESSION, $THEME, $SITE, $COURSE and $USER global variables.
	# All variables should be initialised or at least tested for existence using isset() or empty() before they are used.		# '''All variables should be initialised''' or at least tested for existence using isset() or empty() before they are used.
	# All strings should be translatable - create new texts in the "lang/en_utf8" files with concise English lowercase names and retrieve them from your code using get_string() or print_string(). Never delete strings to ensure backwards compatibility of the language packs is maintained.		# '''All strings should be translatable''' - create new texts in the "lang/en_utf8" files with concise English lowercase names and retrieve them from your code using get_string() or print_string(). Never delete strings to ensure backwards compatibility of the language packs is maintained.
	# Don't use p() and s() functions to print language strings. Those functions are not designed to print html with tags. Use echo() instead.		# '''Don't use p() and s() functions''' to print language strings. Those functions are not designed to print html with tags. Use echo() instead.
	# All errors should be printed using print_error() to maximise translation and help for users (it automatically links to the docs wiki).		# All '''errors should be printed using print_error()''' to maximise translation and help for users (it automatically links to the docs wiki).
	# All help files should be translatable - create new texts in the "lang/en_utf8/help" directory and call them using helpbutton(). If you need to update a help file:		# All '''help files should be translatable''' - create new texts in the "lang/en_utf8/help" directory and call them using helpbutton(). If you need to update a help file:
	#* with a minor change, where an old translation of the file would still make sense, then it's OK to make the change but you should notify translation AT moodle DOT org.		#* with a minor change, where an old translation of the file would still make sense, then it's OK to make the change but you should notify translation AT moodle DOT org.
	#* for a major change you should create a new file by adding an incrementing number (eg filename2.html) so that translators can easily see it's a new version of the file. Obviously the new code and the help index files should also be modified to point to the newest versions.		#* for a major change you should create a new file by adding an incrementing number (eg filename2.html) so that translators can easily see it's a new version of the file. Obviously the new code and the help index files should also be modified to point to the newest versions.
	# Incoming data from the browser (sent via GET or POST) automatically has magic_quotes applied (regardless of the PHP settings) so that you can safely insert it straight into the database. All other raw data (from files, or from databases) must be escaped with addslashes() before inserting it into the database. Because this is so often done incorrectly, there is more explanation on this issue of adding and stripping slashes on a [[Developer:Slashes\|separate page]].		# Incoming data from the browser (sent via '''GET or POST) automatically has magic_quotes applied''' (regardless of the PHP settings) so that you can safely insert it straight into the database. '''All other raw data (from files, or from databases) must be escaped with addslashes()''' before inserting it into the database. Because this is so often done incorrectly, there is more explanation on this issue of adding and stripping slashes on a [[Developer:Slashes\|separate page]].
	# VERY IMPORTANT: All texts ~~within Moodle, especially those that have come from users,~~ should be printed using the format_text() function. This ensures that text is filtered and cleaned correctly. More information can be found on the page about [[Development:Output_functions\|output functions]].		# VERY IMPORTANT: Within Moodle, '''All texts should be printed using the format_text() function''', especially those that have come from users. This ensures that text is filtered and cleaned correctly. More information can be found on the page about [[Development:Output_functions\|output functions]].
	# User actions should be logged using the [[Development:Logs\|add_to_log()]] function. These logs are used for [[Settings#Show_activity_reports\|activity reports]] and [[Logs]].		# User actions should be logged using the [[Development:Logs\|add_to_log()]] function. These logs are used for [[Settings#Show_activity_reports\|activity reports]] and [[Logs]].
	# ~~When generating a~~ HTML ~~link, always make it~~ relative to the full site root, i.e. link to ''$CFG->wwwroot/mod/blonk/view.php?id=99'' rather than just ''view.php?id=99''. This means that your code will work if called by a script in another folder, among other things.		# '''Always create HTML links relative to the full site root''', i.e. link to ''$CFG->wwwroot/mod/blonk/view.php?id=99'' rather than just ''view.php?id=99''. This means that your code will work if called by a script in another folder, among other things.
	# Modules should store ~~their~~ config variables using ''set_config('varname', $value, 'mod/modulename')'' where the last parameter is the path to the module directory.		# Modules should '''store config variables using ''set_config('varname', $value, 'mod/modulename')''''' where the last parameter is the path to the module directory.
	# Respect decimal separators specified in language pack - do not use number_format() directly, instead use format_float() and unformat_float() when displaying or processing floating point numbers (mandatory in 2.0)		# '''Respect decimal separators specified''' in language pack - do not use number_format() directly, instead use format_float() and unformat_float() when displaying or processing floating point numbers (mandatory in 2.0)

	==Coding style==		==Coding style==