Early release of Rector - The power of automated refactoring
Matthias Noback
In October 2020 I asked Tomáš Votruba, the mastermind behind Rector, if we could have a little chat about this tool. I wanted to learn more about it and had spent a couple of days experimenting with it. Tomáš answered all my questions, which was tremendously valuable to me personally. When this happens I normally feel the need to share: there should be some kind of artefact that can be published, so others can also learn about Rector and how to extend it based on your own refactoring needs.
I started writing a blog post but never published it, because it was just too much for a post. Creating automated refactorings is a slightly complex topic after all, and it needs a lot of background information for everyone to follow what’s going on. So a post was not enough. An alternative would be hours of video recordings, but in my opinion that would just be a waste of everyone’s time. In short, this situation actually called for a new book.
After another chat with Tomáš we decided to work on a book together. Making this a collaborative project was a great idea. Although my own team hasn’t used Rector extensively, I was able to bring real-world refactoring needs and extensive experience with test-driven development, and rely on Tomáš’ expert knowledge about Rector itself, and automated refactorings in general, to bundle lots of sound advice on this topic. It still took several months to finish the bigger part of this book. And although there are still a few chapters that need to be finished, we’d like to share with you now the current version of the book, which contains about a 148 pages of very useful content for developers who want to learn how Rector works and how to automatically refactor and improve their code bases.
You can get your copy now with 5 USD discount by using this link: https://leanpub.com/rector-the-power-of-automated-refactoring/c/RELEASE_DAY. When you buy it, make sure to sign up for notifications about future updates so you’ll get an email when we release the final chapters.
Book automation
As a little background information: the book itself is a mostly automated software project. We use:
- PHPStan, to enforce correct types everywhere and learn about potential problems early.
- Rector itself, to enforce certain programming standards, and to help us upgrade the code samples in the book to newer versions of PHP and Rector.
- A custom-made output generation tool that runs processes like PHPUnit and Rector on the code samples before including them in the book. The process output like PHPUnit test results and diffs are persisted so we can easily include them in the manuscript.
- A custom-made manuscript resource generation tool that takes working code samples, crops them, and copies them to the Leanpub’s manuscript folder.
- EasyCodingStandard, to enforce a single code style, and to ensure (most of) the code samples don’t need line wrapping.
This is a very cool approach, and it’s completely different from my previous experiences in book publishing, both with Leanpub and with traditional publishers. With traditional publishing the problem is that you can’t easily make changes to the manuscript once it’s past a certain stage. With Leanpub you can always publish a new version. But if your book has code samples, you often just copy/paste them into the manuscript files. At that point, the code is no longer under test, so you can’t really trust it to be correct, and it becomes very hard to apply a different code style to all the samples at once.
With this automated approach we can just run any tool, then generate the snippets that are actually needed by the manuscript. This means we’ll learn about any problems with upgraded dependencies, and we’ll find out early if a change in Rector itself causes the examples in this book to break.