For a long time, we have had Python code style requirements, but it covers only very basic details and still allows us to write code very differently.
The project grows fast and we have a lot of code now. This is the perfect time to introduce strict(er) code requirements.
I am suggesting to implement:
- Set a single strict style, by using the Ruff (https://docs.astral.sh/ruff/) tool for formatting.
Why Ruff? I tried several alternatives and was an active user of yapf, black, and now ruff. If a tool allows too many settings (yapf) - there is a big temptation to adapt it and always a lot of noise around which of them is better. If a tool is very strict (black) - it is better and easier to use, but it is not very strange to write a new code without reformatting all the previous - because of enforcing " as the main quote character first of all. Ruff offers the best of both worlds - it contains very few settings you can change and is perfectly compatible with the current requirements and style, just makes them more strict.
- Do not accept new/refactored code without typing, annotations, and comments for all functions and classes.
With annotations and comments everything is clear - we already partially require this. Typing adds here more benefits - like better automatic code analysis, predictable outputs, the ability to generate tests and force developers to write better and easier-to-read code (yeah, try to write something that can return multiple or complex types of objects with typing)
- Use ruff as a linter for all new commits for a style and block them if the check fails.
Another useful feature of ruff is that it can not only format the code but can be used as a powerful linter. We tried this in a private repository, and the result was very positive.
- Reformat all the code in the repository to the new style.
This is the hardest decision but seems to be unavoidable if we want to keep the code clean and maintainable. And thanks to .git-blame-ignore-revs, it can be almost transparent in GitHub.
With these changes, we should get a more comfortable environment for developers and better and stricter guidance for contributors.