diff --git a/source/checklists/reviewprocess.rst b/source/checklists/reviewprocess.rst index 8997fcc..9765200 100644 --- a/source/checklists/reviewprocess.rst +++ b/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 diff --git a/source/coding_standards/global.rst b/source/coding_standards/global.rst new file mode 100644 index 0000000..94bf4ed --- /dev/null +++ b/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 + + "; + } + } + + 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 + + '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 `_ 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 diff --git a/source/coding_standards/index.rst b/source/coding_standards/index.rst new file mode 100644 index 0000000..da86263 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/source/coding_standards/javascript.rst b/source/coding_standards/javascript.rst new file mode 100644 index 0000000..12bc7da --- /dev/null +++ b/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. \ No newline at end of file diff --git a/source/codingstandards.rst b/source/coding_standards/php.rst similarity index 98% rename from source/codingstandards.rst rename to source/coding_standards/php.rst index dbddd16..a06ac89 100644 --- a/source/codingstandards.rst +++ b/source/coding_standards/php.rst @@ -3,7 +3,6 @@ Coding standards As of GLPI 10, we rely on `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 `_ 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 . \ No newline at end of file diff --git a/source/index.rst b/source/index.rst index 30bacca..ed559ba 100644 --- a/source/index.rst +++ b/source/index.rst @@ -14,7 +14,7 @@ GLPI Developer Documentation :maxdepth: 2 sourcecode - codingstandards + coding_standards/index devapi/index checklists/index plugins/index diff --git a/source/plugins/requirements.rst b/source/plugins/requirements.rst index 9a1412d..bfff93a 100644 --- a/source/plugins/requirements.rst +++ b/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: