Javascript/Coding Style - Revision history

Andrewnicols at 04:17, 4 October 2021

2021-10-04T04:17:11Z

← Older revision		Revision as of 04:17, 4 October 2021
Line 1:		Line 1:
	The Moodle JavaScript coding style		The Moodle JavaScript coding style.

			{{Deprecated\|version=3.10}}

	== Overview ==		== Overview ==

Andrewnicols: Add note that this style guide is out-of-date.

2021-10-04T04:15:18Z

Add note that this style guide is out-of-date.

← Older revision		Revision as of 04:15, 4 October 2021
Line 9:		Line 9:
	Note that some part of this document, specifically those making a reference to [[YUI\|Yui]] modules, can be considered outdated. Since Moodle 2.9 all javascript is being moved to [[Javascript Modules\|Javascript modules]] and, more recently, since Moodle 3.10, to ES6 Javascript modules (see MDLSITE-6130).		Note that some part of this document, specifically those making a reference to [[YUI\|Yui]] modules, can be considered outdated. Since Moodle 2.9 all javascript is being moved to [[Javascript Modules\|Javascript modules]] and, more recently, since Moodle 3.10, to ES6 Javascript modules (see MDLSITE-6130).

	Please note that all new Javascript should be written using best practice ES-style javascript which is transpiled into ES2015 for backwards compatability. The use of jQuery and YUI in new code is not allowed, except where interfacing with legacy code which requires those objects and/or those features.		Please note that all new Javascript should be written using best practice ES-style javascript which is transpiled into ES2015 for backwards compatability. The use of jQuery and YUI in new code is not allowed, except where interfacing with legacy code which requires those objects and/or those features. Many parts of this document are specific to YUI and, where possible best practice modern JS should be written instead.

			This documented will be replaced in the future with an updated guide.

	=== Goals ===		=== Goals ===

Mudrd8mz: Text replacement - "`" to ""`


2021-07-15T08:24:28Z
Text replacement - "<code (.*)>" to "<syntaxhighlight lang="$1">"
Show changes

`Mudrd8mz: Text replacement - "`" to ""

2021-07-14T13:07:11Z

Text replacement - "</code>" to "</syntaxhighlight>"

Show changes

Andrewnicols: /* Documentation and comments */

2021-07-02T13:26:25Z

Documentation and comments

@@ Line 300: / Line 300: @@
 Modules should be documented using valid [https://jsdoc.app/ JSDoc].
 === General notes ===
@@ Line 306: / Line 308: @@
 * all comments must start with leading whitespace before the first word on each line; and
 * all indentation must be in addition to any existing leading whitespace on the line.
 == Documentation and comments ==

Andrewnicols: Include how to generate docs.

2021-07-02T13:24:53Z

Include how to generate docs.

@@ Line 300: / Line 300: @@
 Modules should be documented using valid [https://jsdoc.app/ JSDoc].
 === General notes ===
@@ Line 317: / Line 329: @@
 A few notes:
-* Docblocks should not make use of the `@package [name]` tag as this is not valid in JSDoc.
+* Docblocks should not make use of the <nowiki>@package [name]</nowiki> tag as this is not valid in JSDoc.
-* JS only has `number`, and does not have separate types for `int` and `float`.
+* JS only has <nowiki>number</nowiki>, and does not have separate types for <nowiki>int</nowiki> and <nowiki>float</nowiki>.
 ==== Correct ====
@@ Line 385: / Line 397: @@
 </code>
 === General comments ===

Andrewnicols: Update for jsdoc

2021-07-02T13:20:01Z

Update for jsdoc

← Older revision		Revision as of 13:20, 2 July 2021
Line 299:		Line 299:
	== Documentation and comments ==		== Documentation and comments ==

	Modules should be documented using ~~the standard YUI guidance: http~~://~~yui~~.~~github.io~~/~~yuidoc/syntax/index.html~~.		Modules should be documented using valid [https://jsdoc.app/ JSDoc].

	=== General notes ===		=== General notes ===
Line 316:		Line 316:
	* have a linebreak between the description and the list of tags.		* have a linebreak between the description and the list of tags.

	~~Note~~:		A few notes:
			* Docblocks should not make use of the `@package [name]` tag as this is not valid in JSDoc.
	YUIDoc will only generate documentation for docblocks starting with /**.		* JS only has `number`, and does not have separate types for `int` and `float`.

	~~YUIDoc will try to generate documentation~~ for ~~all docblocks starting /**~~.

	==== Correct ====		==== Correct ====
Line 326:		Line 324:
	<code javascript>		<code javascript>
	/**		/**
	* ~~This docblock describes~~ a ~~YUI~~ module.		* All ES and AMD modules should have a module directive with the AMD module name.
			*
			* For a module located at question/type/example/amd/src/dothethings.js the module name will be as follows.
	*		*
	* @module ~~moodle-mod_food-marmite~~		* @module qtype_example/dothethings
	*/		*/

	/**		/**
	* ~~This docblock describes~~ the ~~marmite~~ class ~~within~~ the		* If the module defines a class, it should be documented with the class tag.
	* ~~moodle-mod_food-marmite~~ module.		*
			* If the class is the default export for the module, then the name specified should match the module name.
	*		*
	* @class ~~Marmite~~		* @class qtype_example/dothethings
	*/		*/
			export default class {
			// ...
			}

			/**
			* If the module defines multiple classes then they should be namespaced under the module name.
			*
			* @class qtype_example/dothethings/MyClass
			*/
			export const MyClass = class {
			// ...
			}

	/**		/**
Line 344:		Line 357:
	* It adds a number of jars of marmite to the cupboard.		* It adds a number of jars of marmite to the cupboard.
	*		*
	* @method ~~addMarmite~~		* @method
	* @param {Number} [jarCount=1] The number of jars of marmite to add to the		* @param {Number} [jarCount=1] The number of jars of marmite to add to the
	* cupboard. This parameter is optional and defaults to 1.		* cupboard. This parameter is optional and defaults to 1.
	* @chainable
	*/		*/
			export const addMarmite = (jarCount = 1) => {
			// ...
			};

	/**		/**
	* This docblock describes the property weight, in grams.		* This docblock describes the property weight, in grams.
	*		*
	* @property ~~weight~~		* @property {number} weight
	* @type {~~Number~~}
	* @default '500'
	*/

	/**
	* This docblock describes an attribute.
	*
	* @attribute weight
	* @type {Number}
	* @default '500'
	*/		*/
			export const weight = 400;
	</code>		</code>

Line 371:		Line 377:
	<code javascript>		<code javascript>
	/*		/*
	* This ~~is an invalid comment~~ block~~. It wouldn't~~ be picked up by ~~yuidoc~~ as		* This block would not be picked up by jsdoc as it only has a single * in the opening line.
	* the ~~comment style is incorrect~~.
	*		*
	* @method foo		* @method foo
	*/		*/

	// This ~~is also an invalid~~ comment ~~block and wouldn't be picked up by~~		// This comment would not be picked up by jsdoc either.
	~~// YUIDoc.~~

	/**
	* Although this style would be picked up by YUIDoc, it is hard to read.
	*
	* @method foo
	*/

	/**
	*Although this style would be picked up by ~~YUIDoc, it is also hard to read.~~
	*
	*@method foo
	*/

	/**
	* This docblock is mostly valid but does not include a linebreak between
	* the description, and the tags.
	* @method foo
	*/
	</code>		</code>

Andrewnicols: Remind that jQuery/YUI is banned.

2021-04-14T02:44:15Z

Remind that jQuery/YUI is banned.

← Older revision		Revision as of 02:44, 14 April 2021
Line 8:		Line 8:

	Note that some part of this document, specifically those making a reference to [[YUI\|Yui]] modules, can be considered outdated. Since Moodle 2.9 all javascript is being moved to [[Javascript Modules\|Javascript modules]] and, more recently, since Moodle 3.10, to ES6 Javascript modules (see MDLSITE-6130).		Note that some part of this document, specifically those making a reference to [[YUI\|Yui]] modules, can be considered outdated. Since Moodle 2.9 all javascript is being moved to [[Javascript Modules\|Javascript modules]] and, more recently, since Moodle 3.10, to ES6 Javascript modules (see MDLSITE-6130).

			Please note that all new Javascript should be written using best practice ES-style javascript which is transpiled into ES2015 for backwards compatability. The use of jQuery and YUI in new code is not allowed, except where interfacing with legacy code which requires those objects and/or those features.

	=== Goals ===		=== Goals ===

Stronk7: Briefly explain the history of yui/amd/es6

2020-07-28T14:13:52Z

Briefly explain the history of yui/amd/es6

← Older revision		Revision as of 14:13, 28 July 2020
Line 5:		Line 5:
	This document outlines the exceptions to the general Moodle [[Coding_style\|Coding style]] which apply to JavaScript.		This document outlines the exceptions to the general Moodle [[Coding_style\|Coding style]] which apply to JavaScript.

	Unless otherwise specified, developers should follow the general coding style for advice on coding style.		Unless otherwise specified, developers should follow the general coding style for advice on coding style.

			Note that some part of this document, specifically those making a reference to [[YUI\|Yui]] modules, can be considered outdated. Since Moodle 2.9 all javascript is being moved to [[Javascript Modules\|Javascript modules]] and, more recently, since Moodle 3.10, to ES6 Javascript modules (see MDLSITE-6130).

	=== Goals ===		=== Goals ===

Poltawski: MDL-57139: Promises guidance

2017-06-12T14:21:25Z

MDL-57139: Promises guidance

@@ Line 431: / Line 431: @@
   * indicator.
   */
 </code>