Tuleap coding standards

PHP code formatting

As Tuleap is mainly written in PHP, we use the PSR standards:

Rule of thumb: All new classes MUST respect PSR-4

Javascript code formatting

Javascript files (.js) and Vue files (.vue) are parsed by two tools on a pre-commit hook:

  • eslint helps to check for errors, unused variables, strange syntax and other potentially problematic code. Some errors can be automatically fixed, but others cannot.
  • prettier formats code to a universal, opinionated standard. It can format files automatically.

Those tools are not there to annoy you. We enforce these rules to maintain consistency (as much as possible) in the very large and diverse Tuleap codebase. Automated tools also help integrators speed up the review process. Nobody wants to spend hours leaving comments about code style, and nobody wants to spend hours fixing code to satisfy those comments ;).

You should configure your editor or IDE to automatically report linter errors. This will give you the fastest feedback. If some code does not conform to formatting or syntax rules, the pre-commit hook will reject it.

Sass code formatting

Sass files (.scss) are also parsed by an automated tool on a pre-commit hook. We currently use stylelint to automatically check Sass files.

This tool will warn you when you make a mistake in a Sass rule. It will also enforce some stylistic conventions such as using shorthand notations or ordering the properties in rules.

This time also, feel free to configure your editor or IDE to automatically report linting errors. This will give you the fastest feedback. The pre-commit hook will warn you otherwise.

Internal conventions

  • Use an indent of 4 spaces, with no tabs. This helps to avoid problems with diffs, patches, git history…
  • It is recommended to keep lines at approximately 85-100 characters long for better code readability.
  • methodsInCamelCase()
  • $variables_in_snake_case
  • constants in UPPER_CASE
  • public methods documented (at least @return statement)
  • class documented (I'm responsible of…)
  • All added code should follow PSR-2. Existing code should be converted to PSR-2 in a dedicated commit in order to not clutter the review of your functional change.
  • No trailing whitespaces
  • In DataAccessObject, convention is to name searchXxx() the methods that returns a set of rows (eg. searchProjectsUserIsAdmin(…), and getXxx, isXxx, hasXxx for other cases (eg. doesUserHavePermission(…)).

Note

Contributions SHOULD NOT add/fix features AND fix coding standard of a legacy file in the same review. The code WONT be accepted. If your eyes are bleeding, conform to coding standard in a dedicated review, then contribute your change.

This is especially true for refactoring, where the goal is to improve a part of the code. Extracted crappy code to a dedicated file does not need to be refactored, in order to ease the review (You may need to use one of ignore capabilities of phpcs in order to pass coding standards check). Contributor has to focus his mind on one task at a time.

Remember: refactoring is here to improve the existing code without breaking functionality.

Resources