Difference between revisions of "Coding"

Jump to: navigation, search
m (Usability)
(Add link to manual testing instruction guidelines.)
 
(43 intermediate revisions by 13 users not shown)
Line 1: Line 1:
 
This page is the top-level page describing Moodle's coding guidelines.  It's the place to start if you want to know how to write code for Moodle.
 
This page is the top-level page describing Moodle's coding guidelines.  It's the place to start if you want to know how to write code for Moodle.
 
<p class="note">WARNING: Under construction RIGHT NOW!</p>
 
 
  
  
Line 9: Line 6:
 
Moodle tries to run on the widest possible range of platforms, for the widest possible number of people, while remaining easy to install, use, upgrade and integrate with other systems.
 
Moodle tries to run on the widest possible range of platforms, for the widest possible number of people, while remaining easy to install, use, upgrade and integrate with other systems.
  
For more about this, see: [[Moodle architecture]].
+
For more about this, see [[Moodle architecture]].
  
 
==Plugins==  
 
==Plugins==  
  
Moodle has a general philosophy of modularity.  There are over 25 different types of plugins, however many of these plugin types work the same way.
+
Moodle has a general philosophy of modularity.  There are nearly 30 different standard types of plugins and even more sub-plugin types, however all of these plugin types work the same way. Blocks and activities are the only small exceptions.
  
For more about the structure of plugins, see [[Plugins|Moodle plugins]].
+
See [[Plugins|Moodle plugins]] and [[Subplugins|Moodle sub-plugins]] for more information.
  
 
==Coding style==
 
==Coding style==
  
Consistent coding style is important in any development project, and particularly so when many developers are involved. A standard style helps to ensure that the code is easier to read and understand, which helps overall quality.  
+
Consistent [[Coding style|coding style]] is important in any development project, and particularly so when many developers are involved. A standard style helps to ensure that the code is easier to read and understand, which helps overall quality.  
  
Writing your code in this way will ensure your code is an important step to having your code accepted by the Moodle community.
+
Writing your code in this way is an important step to having your code accepted by the Moodle community.
  
 
Our [[Coding_style|Moodle coding style]] document explains this standard.
 
Our [[Coding_style|Moodle coding style]] document explains this standard.
Line 33: Line 30:
 
Any single script (in Moodle core or a third party module) can introduce a vulnerability to thousands of sites, so it's important that all developers strictly follow our [[Security|Moodle security guidelines]].
 
Any single script (in Moodle core or a third party module) can introduce a vulnerability to thousands of sites, so it's important that all developers strictly follow our [[Security|Moodle security guidelines]].
  
==XHTML==
+
==XHTML and CSS==
 +
 
 +
It's important that Moodle produces strict, well-formed [http://en.wikipedia.org/wiki/HTML5 HTML 5] code (preferably backwards compatible with [[XHTML|XHTML 1.1]] if possible), compliant with all common accessibility guidelines (such as [http://www.w3.org/TR/WCAG20/ W3C WAG 2.0], [http://www.w3.org/TR/wai-aria-practices/ ARIA]).
  
It's important that Moodle produces strict, well-formed XHTML code, compliant with all common accessibility guidelines (such as W3C WAG).
+
CSS should be used for layout. Moodle comes with several themes installed. Beginning with version 2.7, only the 'Clean' theme comes in the base Moodle code. The 'standard' theme, which should be a plain theme suitable to act as a building block for other themes. That should contain the minimal styling to make Moodle look OK and be functional. Then Moodle comes with several other default themes that look good and demonstrate various techniques for building themes.
  
 
This helps consistency across browsers in a nicely-degrading way (especially those using non-visual or mobile browsers), as well as improving life for theme designers.
 
This helps consistency across browsers in a nicely-degrading way (especially those using non-visual or mobile browsers), as well as improving life for theme designers.
 
Full information is here:  [[XHTML|Moodle XHTML]]
 
  
 
==JavaScript==
 
==JavaScript==
  
In general, everything in Moodle should work with JavaScript turned off in your browser. If you do have JavaScript enabled it should only improve usability (not add features).
+
In general, everything in Moodle should work with JavaScript turned off in your browser. This is important for accessibility, and in line with the principles of unobtrusive JavaScript and progressive enhancement.  
  
This is important for accessibility, and in line with the principles of unobtrusive JavaScript and progressive enhancement.  
+
Features that are not available without JavaScript must be compliant with all accessibility standards.
  
 
See the [[JavaScript guidelines|Moodle JavaScript guidelines]] for more information.
 
See the [[JavaScript guidelines|Moodle JavaScript guidelines]] for more information.
Line 51: Line 48:
 
==Internationalisation==
 
==Internationalisation==
  
Moodle works in over 81 languages because we pay great attention to keeping the language strings and locale information separate from the code, in language packs.
+
Moodle works in over 84 languages because we pay great attention to keeping the language strings and locale information separate from the code, in language packs.
  
The default language for all code and documentation, however, is English (AU).
+
The default language for all code, comments and documentation, however, is English (AU).
  
Full details:  [[Internationalisation|Moodle Internationalisation]]
+
Full details:  [[String API]]
  
 
==Accessibility==
 
==Accessibility==
Line 61: Line 58:
 
Moodle should work well for the widest possible range of people.
 
Moodle should work well for the widest possible range of people.
  
See: [[Accessibility|Moodle Accessibility]]
+
See [[Accessibility|Moodle Accessibility]] for more information.
  
 
==Usability==
 
==Usability==
  
See: [[Moodle_User_Interface_Guidelines|Moodle User Interface Guidelines]] (being produced summer 2009)
+
See [[Interface_guidelines| Interface Guidelines]] (under construction)
* Implementing user interfaces: [[Interface_guidelines| Interface Guidelines]]
+
 
 +
==Performance==
 +
 
 +
The load any Moodle site can cope with will, of course, depend on the server and network hardware that it is running on. However there are some features (intended especially for developers) that are discouraged on production sites for performance reasons.
 +
 
 +
The most important property is scalability, so a small increase in the number of users, courses, activities in a course, and so on, only causes a correspondingly small increase in server load.
 +
 
 +
For more information and advice, see [[Performance and scalability|Performance and scalability]].
  
 
==Database==
 
==Database==
  
Moodle has a powerful database abstraction layer that we wrote ourselves, called [[XMLDB_Documentation|XMLDB]].  This lets the same Moodle code work on MySQL, PostgreSQL, Oracle and MSSQL.
+
Moodle has a powerful database abstraction layer that we wrote ourselves, called [[XMLDB_Documentation|XMLDB]].  This lets the same Moodle code work on MySQL/MariaDB, PostgreSQL, MS SQL Server and Oracle. There are know issues when using Oracle, it is not fully supported and is not recommended for production sites.
  
We have tools and API for [[DDL functions|defining and modifying tables]] as well as [[DML functions|methods for getting data in and out]] of the database.
+
We have tools and API for [[DDL functions|defining and modifying tables]] as well as [[Data manipulation API|methods for getting data in and out]] of the database.
  
 
Overview: [[Database|Moodle Database]] guidelines
 
Overview: [[Database|Moodle Database]] guidelines
Line 78: Line 82:
 
==Events==
 
==Events==
  
Moodle allows inter-module communication via '''events'''.  Modules can '''trigger''' specific events and other modules can choose to '''handle''' those events.
+
Moodle allows inter-module communication via '''events'''.  Modules can '''trigger''' specific events and other modules can choose to '''handle/observe''' those events.
 +
 
 +
See:
 +
* [[Events_API|Events API]] - Moodle 2.0 - 2.5
 +
* [[Event_2|New Events API]] - Moodle 2.6 and later
 +
 
 +
==Manual testing==
 +
 
 +
All issues integrated into the core codebase are tested both during Integration, and subsequently by our testing team. While much of this testing is automated, there are many parts which cannot be automated, and manual testing is required.
  
Full information:  [[Events_API|Moodle Events API]]
+
Moodle has guidelines on [[Testing_instructions_guide|how to write clear testing instructions]] which we recommend you read and follow.
  
==Unit tests==
+
==Unit testing==
  
 
[http://en.wikipedia.org/wiki/Unit_testing Unit testing] is not simply a technique but a philosophy of software development.
 
[http://en.wikipedia.org/wiki/Unit_testing Unit testing] is not simply a technique but a philosophy of software development.
Line 88: Line 100:
 
The idea is to create automatable tests for each bit of functionality that you are developing (at the same time you are developing it).  This not only helps everyone later test that the software works, but helps the development itself, because it forces you to work in a modular way with very clearly defined structures and goals.
 
The idea is to create automatable tests for each bit of functionality that you are developing (at the same time you are developing it).  This not only helps everyone later test that the software works, but helps the development itself, because it forces you to work in a modular way with very clearly defined structures and goals.
  
Moodle uses a library called simpletest (not very extensively yet though!) that makes writing unit tests fairly simple. Our unit testing is currently not deep but we want to improve this.
+
Moodle uses a framework called [https://github.com/sebastianbergmann/phpunit/ PHPUnit] that makes writing unit tests fairly simple.
 +
 
 +
See [[PHPUnit]] for more information.
 +
 
 +
==Acceptance testing==
  
Full information here: [[Unit_tests|Moodle Unit Tests]]
+
PHPUnit covers mostly the internal implementation of functions and classes, the user interaction testing can be automated using the [http://behat.org Behat framework].
  
== See also ==
+
See [[Acceptance testing]] for more information.
* [http://doku.clausvb.de/php_coding_standard.htm General PHP coding standards]
 
* [http://pear.php.net/manual/en/standards.php PEAR coding standards]
 
  
 +
==Third Party Libraries==
 +
Moodle has a standard way to include third party libraries in your code. See https://docs.moodle.org/dev/Third_Party_Libraries
  
[[Category:Coding]]
+
== Other standards ==
  
[[es:Manual de Estilo de Código]]
+
Please note that Moodle coding style and design is pretty unique, it is not compatible with [http://pear.php.net/manual/en/standards.php PEAR coding standards] or any other common PHP standards.
[[ja:コーディング]]
 
[[zh:代码指南]]
 
[[pl:Kodowanie]]
 
[[pt:manual_de_codigo]]
 
[[fr:Développement:Directives_de_codage]]
 

Latest revision as of 01:23, 1 August 2018

This page is the top-level page describing Moodle's coding guidelines. It's the place to start if you want to know how to write code for Moodle.


Moodle architecture

Moodle tries to run on the widest possible range of platforms, for the widest possible number of people, while remaining easy to install, use, upgrade and integrate with other systems.

For more about this, see Moodle architecture.

Plugins

Moodle has a general philosophy of modularity. There are nearly 30 different standard types of plugins and even more sub-plugin types, however all of these plugin types work the same way. Blocks and activities are the only small exceptions.

See Moodle plugins and Moodle sub-plugins for more information.

Coding style

Consistent coding style is important in any development project, and particularly so when many developers are involved. A standard style helps to ensure that the code is easier to read and understand, which helps overall quality.

Writing your code in this way is an important step to having your code accepted by the Moodle community.

Our Moodle coding style document explains this standard.

Security

Security is about protecting the interests and data of all our users. Moodle may not be banking software, but it is still protecting a lot of sensitive and important data such as private discussions and grades from outside eyes (or student hackers!) as well as protecting our users from spammers and other internet predators.

It's also a script running on people's servers, so Moodle needs to be a responsible Internet citizen and not introduce vulnerabilities that could allow crackers to gain unlawful access to the server it runs on.

Any single script (in Moodle core or a third party module) can introduce a vulnerability to thousands of sites, so it's important that all developers strictly follow our Moodle security guidelines.

XHTML and CSS

It's important that Moodle produces strict, well-formed HTML 5 code (preferably backwards compatible with XHTML 1.1 if possible), compliant with all common accessibility guidelines (such as W3C WAG 2.0, ARIA).

CSS should be used for layout. Moodle comes with several themes installed. Beginning with version 2.7, only the 'Clean' theme comes in the base Moodle code. The 'standard' theme, which should be a plain theme suitable to act as a building block for other themes. That should contain the minimal styling to make Moodle look OK and be functional. Then Moodle comes with several other default themes that look good and demonstrate various techniques for building themes.

This helps consistency across browsers in a nicely-degrading way (especially those using non-visual or mobile browsers), as well as improving life for theme designers.

JavaScript

In general, everything in Moodle should work with JavaScript turned off in your browser. This is important for accessibility, and in line with the principles of unobtrusive JavaScript and progressive enhancement.

Features that are not available without JavaScript must be compliant with all accessibility standards.

See the Moodle JavaScript guidelines for more information.

Internationalisation

Moodle works in over 84 languages because we pay great attention to keeping the language strings and locale information separate from the code, in language packs.

The default language for all code, comments and documentation, however, is English (AU).

Full details: String API

Accessibility

Moodle should work well for the widest possible range of people.

See Moodle Accessibility for more information.

Usability

See Interface Guidelines (under construction)

Performance

The load any Moodle site can cope with will, of course, depend on the server and network hardware that it is running on. However there are some features (intended especially for developers) that are discouraged on production sites for performance reasons.

The most important property is scalability, so a small increase in the number of users, courses, activities in a course, and so on, only causes a correspondingly small increase in server load.

For more information and advice, see Performance and scalability.

Database

Moodle has a powerful database abstraction layer that we wrote ourselves, called XMLDB. This lets the same Moodle code work on MySQL/MariaDB, PostgreSQL, MS SQL Server and Oracle. There are know issues when using Oracle, it is not fully supported and is not recommended for production sites.

We have tools and API for defining and modifying tables as well as methods for getting data in and out of the database.

Overview: Moodle Database guidelines

Events

Moodle allows inter-module communication via events. Modules can trigger specific events and other modules can choose to handle/observe those events.

See:

Manual testing

All issues integrated into the core codebase are tested both during Integration, and subsequently by our testing team. While much of this testing is automated, there are many parts which cannot be automated, and manual testing is required.

Moodle has guidelines on how to write clear testing instructions which we recommend you read and follow.

Unit testing

Unit testing is not simply a technique but a philosophy of software development.

The idea is to create automatable tests for each bit of functionality that you are developing (at the same time you are developing it). This not only helps everyone later test that the software works, but helps the development itself, because it forces you to work in a modular way with very clearly defined structures and goals.

Moodle uses a framework called PHPUnit that makes writing unit tests fairly simple.

See PHPUnit for more information.

Acceptance testing

PHPUnit covers mostly the internal implementation of functions and classes, the user interaction testing can be automated using the Behat framework.

See Acceptance testing for more information.

Third Party Libraries

Moodle has a standard way to include third party libraries in your code. See https://docs.moodle.org/dev/Third_Party_Libraries

Other standards

Please note that Moodle coding style and design is pretty unique, it is not compatible with PEAR coding standards or any other common PHP standards.