Code formatting on autopilot
TL;DR DeepSource Transformers automatically run code formatters like Black, Gofmt, etc. on your pull-requests and commit formatted code with zero effort. You can try it out here — it's free for open-source and up to 3 private repositories.
Code style conventions are important to developers. And for good reasons too — adherence to a consistent style improves readability of the code, allowing anyone who's working with it to understand the existing code more quickly and thoroughly and add new things easily. 40% - 80% of the lifetime cost of a piece of software goes into maintenance, and it pays off to invest in keeping things clean.
Although, agreeing upon a style convention is much harder than it seems to be on surface. Most developers have their personal preferences that they defend with vigor. But the same people also agree that debating on style conventions on every new pull-request is just a waste of time. They just wanted to get done with this.
Code formatters, fortunately, came to the rescue. It all started with Gofmt, the automated code formatter for the Go programming language. It provided an opinionated but consistent way of formatting Go code, with one of the primary goals being removing any controversy about formatting decisions altogether. And it worked! Gofmt quickly became adopted as the de-facto by everyone who's writing Go. Some people even called it the best feature of the language, giving immense legitimacy to the importance of code style conventions in modern programming. Soon, tools like Black and Prettier appeared, bringing the same philosophy for other programming languages.
Problems with manual code-formatting workflows
If you're not using a fancy IDE or pre-commit hooks, you'd still need to run code formatters manually. This causes a number of problems:
- Someone in your team can forget running Gofmt or Black on the code. Not everyone uses IDEs, or even if they do, don't have the formatters installed and configured properly to auto-format on save.
- If you're running the formatter as a CI step, the CI build fails if the code hasn't been already formatted. Someone will then need to manually pull the latest branch, apply formatting, and then push again.
- If the formatting changes are made as part of an existing PR, it can become difficult to review the code, or revert the changes meaningfully.
Clearly, the battle has been only half-won. Code formatters automated formatting code to a consistent style across the entire codebase. Running the formatters is still manual and messy.
Code formatting on autopilot
I came across a discussion on Hacker News about linters and code formatters, when one comment caught my attention.
"I also love just banging out code, saving, and having my editor clean up the formatting for me." — tlrobinson
tlrobinson is right. Code formatting, despite being important for most developers, is also tedious, and can be completely automated. So we decided to take the automation one step ahead of the editor to directly in your PR workflow on GitHub (and GitLab). We built Transfomers — a way to run a code formatter automatically on every pull-request and commit the changes, in zero clicks. Here's how it works:
Step 1: Enable a transformer on DeepSource
Just add two lines in the configuration file, and you're done. You can also enable multiple Transformers if you want.
Step 2: Install DeepSource Autofix
If you're using GitHub, configure DeepSource to automatically commit changes to your PRs.
And done! Going forward, every time someone makes a pull-request on the repository, DeepSource will automatically commit formatting changes after the latest commit.
Emulating how you write code
While designing how Transformers work, we tried to keep the workflow as close to how a developer would actually run a code formatter in an ideal case.
- Transformers intelligently figure out if there is a need for running code formatters by doing context aware diffing of transformed code with the original. If it didn't find any code that needs to be formatted, it cleanly exists without making any commits — simply notifying the developer that there was nothing to transform.
- If there is a need to run formatters, Transformers create a separate commit with the formatting changes and add it to the commit tree of the pull-request. This ensures that the commit history is logically sane, and it is easy to cherry-pick or revert some changes in the future if needed.
- If multiple formatters are enabled, there could be a chance that one formatter overwrites changes of some other formatter. This can cause inconsistencies. Transformers handle this by detecting if there are overwrites in the same file by multiple formatters, and then running formatting repeatedly on that file until a state of consistency is reached.
There are 150K+ manual commits on GitHub right now containing "run black" in the title. And this is just from open-source.
We believe developers waste way too much of their time on workflows like these that can be completely automated reliably. DeepSource's mission is to help developers ship good code, and part of that can be achieved by automating everything that can be automated reliably, saving a ton of time for every developer in the word.
Give Transformers a shot today if you write Python or Go code. It's free for open-source, and for up to 3 private repositories → deepsource.io/signup
