Tools III: Linters

Overview

Teaching: 5 min
Exercises: 10 min

Questions

• How to make the editor pro-actively find errors and code-smells

Objectives

• Remember how to install and use a linter in vscode without sweat

What is linting?

Linters enforce style rules on your code such as:

• disallow one letter variables outside of loops
• use lower_snake_case for variables
• use CamelCase for classes
• disallow nesting more than n deep
• detect code-smells (patterns that are often bugs, e.g. two functions with the same name)
• requiring all code to be appropriately documented

Consistent styles make a code more consistent and easier to read, whether or not you agree with the style. Using an automated linter avoids bike-shedding since the linter is the final arbiter.

Linters can also catch common errors such as:

• code that is never executed
• code with undefined behaviour
• variables that are never used

Why does linting matter?

• Code is read more often than written
• Ensures all code in a project is consistent, even if contributed by multiple authors
• Prevent simple bugs and mistakes
• Linters shortcut the edit-run-debug and repeat workflow
• Setting up a linter in your editor takes 5 minutes
• Those 5 minutes are redeemed across the lifetime of the project

Rules for choosing linters

1. Choose one or more
2. Stick with them

We prefer ruff for fast and modern general linting. ruff is also a great choice for a linter because it incorporates the checks of multiple other linters, such as flake8 and pydocstyle, into a single tool.

You may also see these linters used by some projects:

• flake8 because it is simple
• pylint because it is (too?) extensive
• mypy for preventing type-related code errors

Checkout GitHub.com: Awesome Linters to see the range of linters available for different languages.

Linters in other languages

• R: lintr, with RStudio integration.
• C++: clang-tidy and CppCheck, although compilers can give lots of helpful linter-type warnings. For gcc and clang, it’s a good idea to pass the -Wall, -Wextra and -Wpedantic flags to get extra ones.
• Fortran: fortran-linter and via compilers, like gfortran or Intel’s ifort and ifx

Exercise (10 min)

Setup VS Code:

1. Return to messy.py (now nicely formatted) in VS Code.
2. The output of the configured linters is shown displayed by coloured underlining in the editor, coloured vertical sections of the scroll bar and in the bottom status bar. Mouse over the underlined sections of the editor to see the reason for each.
3. Check the current errors (click on errors in status bar at the bottom).
4. Understand why each error is present and try to correct them.
5. Alternatively, try and disable them (but remember: with great power…). We’ve already disabled-one at the function scope level. Check what happens if you move it to the top of the file at the module level.

Key Points

• Linting is about discovering errors and code-smells before running the code

• It shortcuts the “edit-run-debug and repeat” workflow

• Almost all editors and IDEs have some means to setup automatic linting

• 5 minutes to setup a linter is redeemed across the time of the project i.e. the cost is close to nothing