doc/coding-standards.md

   1 # Tuleap coding standards
   2
   3 ## PHP code formatting
   4
   5 As Tuleap is mainly written in PHP, we use the PSR standards:
   6
   7 -   [PSR-1](https://www.php-fig.org/psr/psr-1/)
   8 -   [PSR-12](https://www.php-fig.org/psr/psr-12/)
   9 -   [PSR-4](https://www.php-fig.org/psr/psr-4/)
  10
  11 Rule of thumb: *All new classes MUST respect PSR-4*
  12
  13 ### Javascript code formatting
  14
  15 Javascript files (.js) and Vue files (.vue) are parsed by two tools on a
  16 pre-commit hook:
  17
  18 -   [eslint](https://eslint.org/) helps to check for errors, unused
  19     variables, strange syntax and other potentially problematic code.
  20     Some errors can be automatically fixed, but others cannot.
  21 -   [prettier](https://prettier.io/) formats code to a universal,
  22     opinionated standard. It can format files automatically.
  23
  24 Those tools are not there to annoy you. We enforce these rules to
  25 maintain consistency (as much as possible) in the very large and diverse
  26 Tuleap codebase. Automated tools also help integrators speed up the
  27 review process. Nobody wants to spend hours leaving comments about code
  28 style, and nobody wants to spend hours fixing code to satisfy those
  29 comments ;).
  30
  31 You should configure your editor or IDE to automatically report linter
  32 errors. This will give you the fastest feedback. If some code does not
  33 conform to formatting or syntax rules, the pre-commit hook will reject
  34 it.
  35
  36 ### Sass code formatting
  37
  38 Sass files (.scss) are also parsed by an automated tool on a pre-commit
  39 hook. We currently use [stylelint](https://stylelint.io/) to
  40 automatically check Sass files.
  41
  42 This tool will warn you when you make a mistake in a Sass rule. It will
  43 also enforce some stylistic conventions such as using shorthand
  44 notations or ordering the properties in rules.
  45
  46 This time also, feel free to configure your editor or IDE to
  47 automatically report linting errors. This will give you the fastest
  48 feedback. The pre-commit hook will warn you otherwise.
  49
  50 ### Internal conventions
  51
  52 -   Use an indent of 4 spaces, with no tabs. This helps to avoid
  53     problems with diffs, patches, git history...
  54 -   It is recommended to keep lines at approximately 85-100 characters
  55     long for better code readability.
  56 -   methodsInCamelCase()
  57 -   \$variables_in_snake_case
  58 -   constants in UPPER_CASE
  59 -   public methods documented (at least \@return statement)
  60 -   class documented (`I'm responsible of…`)
  61 -   All added code should follow PSR-12. Existing code should be
  62     converted to PSR-12 in a dedicated commit in order to not clutter
  63     the review of your functional change.
  64 -   No trailing whitespaces
  65 -   In DataAccessObject, convention is to name `searchXxx()` the methods
  66     that returns a set of rows (eg. `searchProjectsUserIsAdmin(…)`, and
  67     `getXxx`, `isXxx`, `hasXxx` for other cases (eg.
  68     `doesUserHavePermission(…)`).
  69
  70 ### What's in my contribution ?
  71
  72 Contributions SHOULD NOT add/fix features AND fix coding standard of a
  73 legacy file in the same review. The code WONT be accepted. If your eyes
  74 are bleeding, conform to coding standard in a dedicated review, then
  75 contribute your change.
  76
  77 This is especially true for refactoring, where the goal is to improve a
  78 part of the code. Extracted crappy code to a dedicated file does not
  79 need to be refactored, in order to ease the review (You may need to use
  80 one of [ignore capabilities of
  81 phpcs](https://github.com/squizlabs/PHP_CodeSniffer/wiki/Advanced-Usage#ignoring-files-and-folders)
  82 in order to pass coding standards check). Contributor has to focus his
  83 mind on one task at a time.
  84
  85 Remember: refactoring is here to improve the existing code without
  86 breaking functionality.
  87 :::
  88
  89 ### Copyright & license
  90
  91 All source code files (php, js, bash, \...) must contain a page-level
  92 docblock at the top of each file. This header includes your copyright
  93 and a reference to the license GPLv2+ of the script.
  94
  95 > ``` php
  96 > /**
  97 >  * Copyright (c) <You>, <Year>. All rights reserved
  98 >  *
  99 >  * This file is a part of Tuleap.
 100 >  *
 101 >  * Tuleap is free software; you can redistribute it and/or modify
 102 >  * it under the terms of the GNU General Public License as published by
 103 >  * the Free Software Foundation; either version 2 of the License, or
 104 >  * (at your option) any later version.
 105 >  *
 106 >  * Tuleap is distributed in the hope that it will be useful,
 107 >  * but WITHOUT ANY WARRANTY; without even the implied warranty of
 108 >  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 109 >  * GNU General Public License for more details.
 110 >  *
 111 >  * You should have received a copy of the GNU General Public License
 112 >  * along with Tuleap. If not, see <http://www.gnu.org/licenses/
 113 >  */
 114 > ```
 115
 116 Adapt the copyright line to your situation.