Linting

Note: This page is a work-in-progress. Feedback and suggested improvements are welcome. Please join the discussion on moodle.org or use the page comments.

In Moodle development code linters are used to help ensure consistent coding conventions and help prevent common errors in code.

Motivation

Linting is used to ensure consistent coding style, detect common errors and enforce best practices. At it's best linting helps developers learn, with editor integration and fast feedback meaning that human code reviews can focus on the non-trivial details while linter can be the tireless mistake-preventing machine.

Linters

PHP (PHP_CodeSniffer)

PHP code is linted by PHP_CodeSniffer. The rules defined as part of the Code-checker plugin and if that plugin is installed to Moodle you can use the web user interface to check files. When configuring other PHP_CodeSniffer integrations the path to the rules file is /path/to/local_codechecker/moodle/ruleset.xml. There are future plans (CONTRIB-6209) to move the rules into a more distributable form separate from the codechecker plugin itself.

Javascript (ESLint)

Moodle 3.2

Javascript code is linted with eslint.

Grunt

ESlint is run as part of the build process with grunt. When building Javascript with grunt js AMD and YUI modules are linted and lint errors will cause the build to fail. By default, lint warnings are not displayed, but they can be displayed with the flag `--show-lint-warnings`.

Rules

ESlint rules are defined within .eslintrc and the ESlint website provides good documentation on each rules' purpose and examples of correct and incorrect code for each rule.

Auto fixes Many eslint rules come with auto fixes which allows eslint to fix many problem in place, you can run this fix using the CLI tool `eslint --fix /path/to/file.js` or some text editor plugins such as Visual Studio Code are able to auto fix directly from your editor.

Disabling rules

In some cases it is desirable to disable eslint rules for a certain section of code or a particular rule. It is possible to do this with inline comments like the following examples: /* eslint-disable no-alert */ alert('foo'); /* eslint-enable */

alert('foo'); // eslint-disable-line no-alert

// eslint-disable-next-line no-alert alert('foo');

For full details, see the eslint documentation.

Note: disabling eslint rules should be used sparingly and it is best practice to accompany the disabled line with a comment justifying the rationale.

CSS/SCSS/LESS (stylelint)

Moodle 3.2

CSS (including SCSS and LESS) is linted by stylelint.

Grunt

Stylelint is run as part of the build process with grunt. When grunt css is run, all CSS, SCSS and Less will be linted and any lint problems will cause the build to fail.

Rules

Stylelint rules are defined within .stylelintrc and the Stylelint website provides good documentation on each rules' purpose and examples of correct and incorrect code for each rule.

Reformating CSS with stylefmt

A counterpart tool to stylelint is stylefmt. stylefmt is a tool that automatically formats CSS according to stylelint rules and can be used to reformat existing css files which are out of style. Note that at the time of writing this tool does not have scss/less native compatibility.

Disabling rules

In some cases it is desirable to disable stylelint rules. It is possible to do this with inline comments like the following examples: /* stylelint-disable declaration-no-important */

1. id {

 color: pink !important;

} /* stylelint-enable */

1. id {

 color: pink !important; /* stylelint-disable-line declaration-no-important */

}

1. id {

 /* stylelint-disable-next-line declaration-no-important */
 color: pink !important;

} For full details, see the stylelint documentation.

Note: disabling stylelint rules should be used sparingly and it is best practice to accompany the disabled line with a comment justifying the rationale.