From e7a2644caee7f659405de8b2fc8128bc03c76668 Mon Sep 17 00:00:00 2001 From: cconard96 Date: Sat, 2 Oct 2021 10:26:58 -0400 Subject: [PATCH 1/3] Split global and PHP coding standards --- source/checklists/reviewprocess.rst | 2 +- source/coding_standards/global.rst | 90 +++++++++++++++++++ source/coding_standards/index.rst | 10 +++ .../php.rst} | 2 - source/index.rst | 2 +- source/plugins/requirements.rst | 2 +- 6 files changed, 103 insertions(+), 5 deletions(-) create mode 100644 source/coding_standards/global.rst create mode 100644 source/coding_standards/index.rst rename source/{codingstandards.rst => coding_standards/php.rst} (99%) 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..591aaeb --- /dev/null +++ b/source/coding_standards/global.rst @@ -0,0 +1,90 @@ +Global Coding standards +======================= + +Indentation +----------- + +- 3 spaces +- Max line width: 100 + +.. 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 = []; diff --git a/source/coding_standards/index.rst b/source/coding_standards/index.rst new file mode 100644 index 0000000..76e9666 --- /dev/null +++ b/source/coding_standards/index.rst @@ -0,0 +1,10 @@ +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 \ No newline at end of file diff --git a/source/codingstandards.rst b/source/coding_standards/php.rst similarity index 99% rename from source/codingstandards.rst rename to source/coding_standards/php.rst index dbddd16..7a3bc19 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 -------- 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: From 655470b4bc0eb1d5241102787c0a0ad0cf135412 Mon Sep 17 00:00:00 2001 From: cconard96 Date: Sat, 2 Oct 2021 17:15:56 -0400 Subject: [PATCH 2/3] Add JS coding standards --- source/coding_standards/global.rst | 40 +++++++- source/coding_standards/index.rst | 3 +- source/coding_standards/javascript.rst | 121 +++++++++++++++++++++++++ source/coding_standards/php.rst | 2 +- 4 files changed, 162 insertions(+), 4 deletions(-) create mode 100644 source/coding_standards/javascript.rst diff --git a/source/coding_standards/global.rst b/source/coding_standards/global.rst index 591aaeb..94bf4ed 100644 --- a/source/coding_standards/global.rst +++ b/source/coding_standards/global.rst @@ -4,8 +4,10 @@ Global Coding standards Indentation ----------- -- 3 spaces -- Max line width: 100 +Line length SHOULD NOT exceed 100 characters but there is no hard limit. + +Line indentation MUST be 3 spaces. + .. code-block:: php @@ -88,3 +90,37 @@ Variables and Constants $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 index 76e9666..da86263 100644 --- a/source/coding_standards/index.rst +++ b/source/coding_standards/index.rst @@ -7,4 +7,5 @@ GLPI has a general set of coding standards and then additional requirements for :maxdepth: 2 global.rst - php.rst \ No newline at end of file + 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..c3e668c --- /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 *camelCaps*: + +.. 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/coding_standards/php.rst b/source/coding_standards/php.rst index 7a3bc19..3b6a0a5 100644 --- a/source/coding_standards/php.rst +++ b/source/coding_standards/php.rst @@ -267,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 From 3b845958bd0152698c35fcfef07d29b86322a36e Mon Sep 17 00:00:00 2001 From: cconard96 Date: Sat, 2 Oct 2021 17:28:30 -0400 Subject: [PATCH 3/3] Fix some issues with previous cs docs --- source/coding_standards/javascript.rst | 4 ++-- source/coding_standards/php.rst | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/source/coding_standards/javascript.rst b/source/coding_standards/javascript.rst index c3e668c..12bc7da 100644 --- a/source/coding_standards/javascript.rst +++ b/source/coding_standards/javascript.rst @@ -13,7 +13,7 @@ Starting with GLPI 9.5.0, the target version was bumped to 6 (2015). Functions --------- -Function names must be written in *camelCaps*: +Function names must be written in *camelCase*: .. code-block:: JavaScript @@ -37,7 +37,7 @@ 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`. +Class names must be written in *PascalCase*. ..code-block:: JavaScript diff --git a/source/coding_standards/php.rst b/source/coding_standards/php.rst index 3b6a0a5..a06ac89 100644 --- a/source/coding_standards/php.rst +++ b/source/coding_standards/php.rst @@ -72,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. @@ -95,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? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^