JavaScript coding standards

source/checklists/reviewprocess.rst

@@ -10,7 +10,7 @@ Here is the process you must follow when you are reviewing a PR.
 
 2. Check if unit tests are not failing,
 3. Check if coding standards checks are not failing,
-4. Review the code itself. It must follow :doc:`GLPI's coding standards <../codingstandards>`,
+4. Review the code itself. It must follow :doc:`GLPI's coding standards <../coding_standards/index>`,
 5. Using the Github review process, approve, request changes or just comment the PR,
 
   * If some new methods are added, or if the request made important changes in the code, you should ask the developer to write some more unit tests

source/coding_standards/global.rst

@@ -0,0 +1,126 @@
+Global Coding standards
+=======================
+
+Indentation
+-----------
+
+Line length SHOULD NOT exceed 100 characters but there is no hard limit.
+
+Line indentation MUST be 3 spaces.
+
+
+.. code-block:: php
+
+   <?php
+   // base level
+       // level 1
+           // level 2
+       // level 1
+   // base level
+
+Spacing
+-------
+
+We've adopted "french spacing" rules in the code. The rule is:
+
+* for *simple* punctuation (``,``, ``.``): use *one space after* the punctuation sign
+* for *double* punctuation (``!``, ``?``, ``:``): use *one space after and one space before* the punctuation sign
+* for *opening* punctuation (``(``, ``{``, ``[``): use *one space before* the punctuation sign
+* for *closing* punctuation ( ``)``, ``}``, ``]``): use *one space after* the punctuation sign, excepted for line end, when followed by a semi-colon (``;``)
+
+Of course, this rules only aplies on the source code, not on the strings (translatable strings, comments, ...)!
+
+Control structures
+------------------
+
+Multiple conditions in several idented lines
+
+.. code-block:: php
+
+   <?php
+   if ($test1) {
+      for ($i=0 ; $i<$end ; $i++) {
+         echo "test ".( $i<10 ? "0$i" : $i )."<br>";
+      }
+   }
+
+   if ($a==$b
+      || ($c==$d && $e==$f)) {
+     ...
+   } else if {
+     ...
+   }
+
+   switch ($test2) {
+      case 1 :
+         echo "Case 1";
+         break;
+
+      case 2 :
+         echo "Case 2";
+         // No break here : because...
+
+      default :
+         echo "Default Case";
+   }
+
+true, false and null
+--------------------
+
+``true``, ``false`` and ``null`` constants mut be lowercase.
+
+Variables and Constants
+-----------------------
+
+* Variable names must be as descriptive and as short as possible, stay clear and concise.
+* In case of multiple words, use the ``_`` separator,
+* Variables must be **lower case**,
+* Global PHP variables and constants must be **UPPER case**.
+
+.. code-block:: php
+
+   <?php
+   $user         = 'glpi';
+   // put elements in alphabetic order
+   $users        = ['glpi', 'glpi2', 'glpi3'];
+   $users        = ['glpi1'   => 'valeur1',
+                         'nexglpi' => ['down' => '1',
+                                            'up'   => ['firstfield' => 'newvalue']],
+                         'glpi2'   => 'valeur2'];
+   $users_groups = ['glpi', 'glpi2', 'glpi3'];
+
+   $CFG_GLPI = [];
+
+Checking standards
+------------------
+
+In order to check some stabdards are respected, we provide some custom `PHP CodeSniffer <http://pear.php.net/package/PHP_CodeSniffer>`_ rules. From the GLPI directory, just run:
+
+.. code-block:: bash
+
+   phpcs --standard=vendor/glpi-project/coding-standard/GlpiStandard/ inc/ front/ ajax/ tests/
+
+If you want to check the coding standard for the main GLPI codebase, you can use the provided Composer script.
+
+.. code-block:: bash
+
+   composer run-script cs
+
+If the above commands do not provide any output, then, all is OK :)
+
+An example error output would looks like:
+
+.. code-block:: bash
+
+   phpcs --standard=vendor/glpi-project/coding-standard/GlpiStandard/ inc/ front/ ajax/ tests/
+
+   FILE: /var/www/webapps/glpi/tests/HtmlTest.php
+   ----------------------------------------------------------------------
+   FOUND 3 ERRORS AFFECTING 3 LINES
+   ----------------------------------------------------------------------
+    40 | ERROR | [x] Line indented incorrectly; expected 3 spaces, found
+       |       |     4
+    59 | ERROR | [x] Line indented incorrectly; expected 3 spaces, found
+       |       |     4
+    64 | ERROR | [x] Line indented incorrectly; expected 3 spaces, found
+       |       |     4

source/coding_standards/index.rst

@@ -0,0 +1,11 @@
+Coding standards
+================
+
+GLPI has a general set of coding standards and then additional requirements for specific languages/file types (PHP, JavaScript, Twig, etc).
+
+.. toctree::
+   :maxdepth: 2
+
+   global.rst
+   php.rst
+   javascript.rst

source/coding_standards/javascript.rst

@@ -0,0 +1,121 @@
+JavaScript Coding standards
+===========================
+
+ECMAScript Level
+----------------
+
+All JavaScript code should be written to support the target ECMAScript version specified for the version of GLPI you are writing the code for.
+This version can be found in the `.eslintrc.json` file in the `parserOptions.ecmaVersion` property.
+
+For reference, versions of GLPI before 9.5.0 had a target ECMAScript version of 5 due to its support of Internet Explorer 11.
+Starting with GLPI 9.5.0, the target version was bumped to 6 (2015).
+
+Functions
+---------
+
+Function names must be written in *camelCase*:
+
+.. code-block:: JavaScript
+
+   function getUserName(a, b = 'foo') {
+      //do something here!
+   }
+
+   class ExampleClass {
+
+      getUserName(a, b = 'foo') {
+         //do something here!
+      }
+   }
+
+Space after opening parenthesis and before closing parenthesis are forbidden. For parameters which have a default value, add a space before and after the equals sign.
+
+All functions MUST have a JSDoc block especially if it has parameters or is not a simple getter/setter.
+
+Classes
+-------
+
+If you are writing code for versions of GLPI before 9.5.0, you may not use classes as class support was added in EMCAScript 6.
+
+Class names must be written in *PascalCase*.
+
+..code-block:: JavaScript
+
+   class ExampleClass {
+
+   }
+
+   class ExampleClass extends BaseClass {
+
+   }
+
+In general, you should create a new file for each class.
+
+Comments
+--------
+
+For simple or one-line comments, use `//`.
+
+For multi-line or JSDoc comments, use '/** */'
+
+Function JSDoc blocks MUST contain:
+
+- Description
+- Parameter types and descriptions
+- Return type
+
+Function JSDoc blocks SHOULD contain:
+
+- The version of GLPI or the plugin that the function was introduced
+
+.. code-block:: JavaScript
+
+    /**
+     * Short description (single line)
+     *
+     * This is an optional longer description that can span
+     * multiple lines.
+     *
+     * @since 10.0.0
+     *
+     * @param {{}} a First parameter description
+     * @param {string} b Second parameter description
+     *
+     * @returns {string}
+     */
+    function getUserName(a, b = 'foo') {
+
+    }
+
+JSDoc sections MUST be in the following order with an empty line between them:
+
+- Short description (one line)
+- Long description
+- '@deprecated'
+- '@since'
+- '@param'
+- '@return'
+- '@see'
+- '@throw'
+- '@todo'
+
+Variable types
+--------------
+
+When type hinting in JSDoc blocks, you MAY use any of the native types or class names.
+
+If you want to create custom types/object shapes without creating a class, you MAY define a new type using the JSDoc '@typedef' tag.
+
+Quoting Strings
+---------------
+
+Using single quotes for simple strings is preferred. If you are writing for GLPI 9.5.0 or higher, you may use the ECMAScript 6 template literals feature.
+
+When your strings contain HTML content, you SHOULD use template literals (if possible). This lets you format your HTML across multiple lines for better readability and easily inject variable values without concatenation.
+
+Files
+-----
+
+Regular JavaScript files MUST have only lowercase characters in the name. If using modules, the file name MAY have captialized characters.
+
+JavaScript files for tests MAY contain uppercase characters.

source/codingstandards.rst → source/coding_standards/php.rst

@@ -3,7 +3,6 @@ Coding standards
 
 As of GLPI 10, we rely on `PSR-12 <https://www.php-fig.org/psr/psr-12/>`_ for coding standards.
 
-
 Call static methods
 -------------------
 
@@ -40,7 +39,6 @@ When you do not have any object instance yet; the first solution is probably the
 
 On the other hand; if you already have an object instance; you should better use any of the solution but the late static binding. That way; you will save performances since this way to go do have a cost.
 
-
 Comments
 --------
 
@@ -74,7 +72,7 @@ For each method or function documentation, you'll need at least to have a descri
       //[...]
    }
 
-Some other informations way be added; if the function requires it.
+Some other information may be added if the function requires it.
 
 Refer to the `PHPDocumentor website <https://phpdoc.org/docs/latest>`_ to get more informations on documentation.
 
@@ -97,7 +95,7 @@ Parameters documentation
 Each parameter must be documented in its own line, begining with the ``@param`` tag, followed by the `Variables types`_, followed by the param name (``$param``), and finally with the description itself.
 If your parameter can be of different types, you can list them separated with a ``|`` or you can use the ``mixed`` type; it's up to you!
 
-All parameters names and description must be aligned vertically on the longest (plu one character); see the above example.
+All parameters names and description must be aligned vertically on the longest (plus one character); see the above example.
 
 Override method: @inheritDoc? @see? docblock? no docblock?
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -269,4 +267,4 @@ To automatically fix most of the issues, use `phpcbf`, it will per default rely
 
 .. code-block::
 
-   phpcbf .
+   phpcbf .

source/index.rst

@@ -14,7 +14,7 @@ GLPI Developer Documentation
    :maxdepth: 2
 
    sourcecode
-   codingstandards
+   coding_standards/index
    devapi/index
    checklists/index
    plugins/index

source/plugins/requirements.rst

@@ -237,7 +237,7 @@ For instance, a plugin need both an install and an uninstall hook calls. Here is
 Coding standards
 ^^^^^^^^^^^^^^^^
 
-You must respect GLPI's :doc:`global coding standards <../codingstandards>`.
+You must respect GLPI's :doc:`global coding standards <../coding_standards/index>`.
 
 In order to check for coding standards compliance, you can add the `glpi-project/coding-standard` to your composer file, using: