This week I set up static analysis tools for my open source project, go-go-web. I also integrated them into my editor - VS Code, by installing extensions.

My project is written in Python, so I found a formatter and linter to use:

• autopep8
• Pylint

autopep8

autopep8 automatically formats Python code to the PEP 8 style guide. It is very easy to use.

To install: pip install --upgrade autopep8

To run on all files in current directory: python -m autopep8 --in-place --recursive --exclude=<files to ignore> .

Alternatively, if you install the VS Code extension, it can be run by: Right Click File Contents > Format Document With... > autopep8

Pylint

Pylint analyzes code, checking for errors and enforcing a coding standard. When you run it with the following command, it evaluates your code, detailing the problems it found and giving a score out out 10. Fixing the problems it found can raise the score.

Install

To install: pip install pylint

Optional: Create a .pylintrc file in your root directory if you want to customize pylint (see example here)

Issues with Pylint

• No way to run recursively on the current working directory
• To run on the current directory, do NOT run pylint . You may get a misleading result. Use pylint ./*.py or pylint *.py.
• Try python -m pylint if you have trouble getting it to run

Run

Run on CWD: pylint *.py

Run on multiple files/dir: pylint *.py src/ tests/

Run and ignore files: pylint *.py src/ tests/ --ignore-patterns="_version.py,utils.py"

Disable checking a specific type of error by adding a comment at the top of the file: # pylint: disable=line-too-long

Alternatively, if you install the VS Code extension, it automatically runs on every file you open, underlining the error it found. See docs here.

Automate Pylint for GitHub

To setup Pylint to run on each GitHub code push / pull, see my post on CI Workflows here

Issues Pylint found in my code:

• missing function docstring
• line of code is too long
• catching too general of an exception
• calling a variable before it is declared

After I installed Pylint, I saw that the score on my code was 8.9, and after I fixed each problem, I got it to 10. See commit 474ad1 for my code changes.

Contributing Guidelines

I created a CONTRIBUTING.md file, where I outlined step-by-step instructions for how to contributing to my open source project.

I also gave detailed instructions for how to install autopep8 and Pylint and run them prior to creating a pull request.

Reflection

I learned that linters and formatters are very static analysis tools, and I should really have been using them earlier. They not only save me time from formatting my code manually, but they also allow me to identify potential errors early on before it becomes a problem later (when the program gets bigger). I especially recommend installing the Pylint VS Code extension, since it automatically runs on every opened file and highlights errors immediately even without having to run the program.

Lastly it is very important to set up these tools prior to getting others to collaborate on an open source project, since it enforces good formatting and coding standards :)