Enhancing Code Quality: Adding Formatters and Linters to Code-Formatter-Advisor

In this post, I want to share my journey of integrating various code quality tools into my project, Code-Formatter-Advisor. These tools helped me improve the overall quality, readability, and maintainability of the codebase, and I'm hoping this guide can help others interested in enhancing their own projects.

Tools I Chose

For this project, I chose the following tools:

1. Black (Python Code Formatter) - Black is a widely used opinionated Python code formatter that helps standardize the look of Python code. Its primary advantage is that it eliminates arguments over style, helping teams stay productive.

2. Flake8 (Python Linter) - Flake8 is a linting tool that combines PEP 8 compliance checks, pyflakes, and other plugins to catch issues in the code. It's easy to set up and gives comprehensive feedback to identify and fix errors.

Why I Chose These Tools

• Black was chosen for its simplicity and for being highly opinionated, meaning it requires minimal configuration and is effective in keeping everyone on the same page regarding style.
• Flake8 was chosen because it offers a good balance between error detection and style consistency, while being easy to integrate into the existing workflow.

Setting Up the Tools

1. Setting Up Black

First, I installed Black by running the command:

pip install black

To apply Black to the project, I configured it to format Python files on the entire project. I also created a simple script (run_formatter.sh) to run Black from the command line:

#!/bin/bash
black .

2. Setting Up Flake8

Similarly, I installed Flake8 via:

pip install flake8

I added a configuration file .flake8 to specify the max line length and files to exclude:

[flake8]
max-line-length = 88
exclude = venv, __pycache__, migrations

I also created a script (run_linter.sh) to execute Flake8 from the command line:

#!/bin/bash
flake8

Configuring Both Tools

To make it easy for contributors to use these tools, I documented these steps in a CONTRIBUTING.md file and added them to my GitHub repository. Contributors can run ./run_formatter.sh and ./run_linter.sh to apply these tools.

Issues Found by the Tools

Once I ran Black, it reformatted most of my code to ensure a consistent style. There were a few areas where indentation and spacing were corrected, and it also enforced line breaks for long lines.

When running Flake8, it detected some common issues such as:

• Line length violations: Several lines were longer than the configured limit (88 characters).
• Unused imports: Flake8 flagged unnecessary imports, allowing me to clean up the code.

Integrating Tools into VS Code

I also integrated Black and Flake8 with Visual Studio Code (VS Code) to ensure real-time feedback during coding. Here are the steps I followed:

1. Install Python Extension: The official Python extension for VS Code supports Black and Flake8. It provides linting and formatting features automatically.

2. Enable Formatting with Black: I configured VS Code to use Black for formatting upon saving. This was done by adding the following to the VS Code settings (.vscode/settings.json):
   

   {
     "python.formatting.provider": "black",
     "editor.formatOnSave": true
   }

1. Enable Linting with Flake8: Similarly, I enabled Flake8 as the linter by setting:

   {
     "python.linting.flake8Enabled": true,
     "python.linting.enabled": true
   }

Command Line Integration

To run these tools from the command line, I provided the run_formatter.sh and run_linter.sh scripts, which help developers easily run formatting and linting tasks on the entire project without needing to remember complex commands.

What I Learned

This process was insightful as it highlighted several best practices for improving code quality:

1. Automation is Key: Automating code formatting and linting makes the development process smoother and less error-prone. Developers can focus on coding rather than worrying about stylistic details.

2. Integration with Editor: Real-time linting and formatting while writing code make it easier to maintain standards and fix issues on the spot.

3. Code Quality Tools Save Time: Implementing these tools improved readability and maintainability, ultimately making the codebase easier to work with for everyone.

Conclusion

Using Black and Flake8 helped enhance the quality of the Code-Formatter-Advisor project significantly. If you’re considering improving your project’s code quality, I recommend trying these tools for Python projects. I hope this guide helps others set up a similar workflow!