Linting
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.
Lint status in Moodle core
As thousands of lines of Moodle php code was written before linting was introduced, lint errors are present in some parts of existing code. See Should_coding_style_issues_in_existing_code_be_fixed for guidance of when to fix lint issues in existing code.
Excluding code from linting
In certain situations, you may wish to exclude a part of the code from checking by the CodeSniffer. This should be done in very rare cases and the reasons for it must be well documented in the code. An example of such exclusion is to declare that the script is supposed to be used by anonymous internet users - so that the login check does not apply. The CodeSniffer supports this via special inline tags like phpcs:disable and phpcs:disable. For full details, please refer to the Ignoring Parts of a File section of the CodeSniffer wiki.
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.
Lint status in Moodle core
As thousands of lines of Moodle Javascript was written before linting was introduced, lint errors are present in some parts of existing code. See Should_coding_style_issues_in_existing_code_be_fixed for guidance of when to fix lint issues in existing code.
- New Javascript is expected to be lint free
- All AMD modules are lint free - no errors or warnings exist and new errors are prevented from being introduced with grunt js.
- YUI modules are also free of lint errors and enforced by grunt js, though some warnings are present.
- Non-module files have existing lint issues
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 */
- id {
color: pink !important;
}
/* stylelint-enable */
- id {
color: pink !important; /* stylelint-disable-line declaration-no-important */
}
- 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.
Lint status in Moodle core
All CSS in Moodle core is lint free and we prevent new lint errors being introduced with grunt css.
Linting in your editor
Atom
Atom has good support for linting with the linter package and sub-packages
Required configuration:
"linter-phpcs":
codeStandardOrConfigFile: "/path/to/local_codechecker/moodle/"
Eclipse
https://github.com/angelozerr/tern.java/wiki/Tern-Linter-ESLint
PHPStorm
PHPStorm comes with native support for all our linting tools.
- PHP Code Sniffer
- ESlint enabled in: Languages and Frameworks | JavaScript | Code Quality Tools | ESLint
- Stylelint enabled in: Languages and Frameworks | Stylesheets | Stylelint
Sublime
- http://sublimelinter.readthedocs.io/en/latest/
- https://github.com/roadhump/SublimeLinter-eslint
- https://github.com/kungfusheep/SublimeLinter-contrib-stylelint
- http://benmatselby.github.io/sublime-phpcs/
"linters": {
"eslint": {
"@disable": false,
"args": [],
"excludes": []
},
"phpcs": {
"@disable": false,
"args": [],
"excludes": [],
"standard": “/path/to/moodle-local_codechecker/moodle/"
}}
Vim
Good support with syntastic.
let g:syntastic_always_populate_loc_list = 1
let g:syntastic_auto_loc_list = 1
let g:syntastic_check_on_open = 1
let g:syntastic_check_on_wq = 1
let g:syntastic_javascript_checkers = ['eslint']
let g:syntastic_php_checkers = ['php', 'phpcs']
let g:syntastic_php_phpcs_args='--standard="/path/to/local_codechecker/moodle/"'
Visual Studio Code
Required configuration:
"phpcs.standard": "/path/to/local_codechecker/moodle",
Re phpcs: Note you have to install version 2.* of phpcs - not the latest version 3.5.5, and download PHPCSAliases otherwise it doesn't work. See https://moodle.org/mod/forum/discuss.php?d=383557#p1547301
