At the moment I'm writing, I have no work experience, so my only way to practically learn about software development is via open source projects. Some time ago, I released the first version of Answerable, my first open source Python project.
MiguelMJ
/
Answerable
Recommendation system for Stack Overflow unanswered questions
Although I had known Python for a long time, I had always used it for personal projects and college assignments. For this reason, when I made my code open I had to ask questions, accept criticism and see what others did. Here I want to show you some things I learnt about.
Style, PEP 8 and Black
When you make a project open source, you want to make the code accessible and clear. Anyone recognizes spaghetti code when they see it, no matter what their personal coding style is. You must cover some minimums here.
Also, a core part of the Python philosophy is code readability. The first tenet in the Zen of Python reads:
Beautiful is better than ugly.
So, as I saw some references here and there about a document called PEP 8 -- Style Guide for Python Code, I started reading it to learn it and apply it to my code.
Soon, I was told that it was a waste of time when I could use a code formatter like Black. It is easy to learn and use and the improvement is immediately noticeable. You can correct your files on the spot or just print a diff with the changes without really applying them.
Example 1. Formatting files directly:
Example 2. Printing the diff without change:
However, I don't think reading the PEP 8 is a waste of time. Black may ignore some things that you still should pay attention to in order to have a clean style. Still, it is really good for general style revisions.
Checking the code with pyflakes and vulture
Some errors in the code won't be noticed until execution, but they can be prevented with a meticulous review beforehand. The same happens with dead code that's been left after some changes. Pyflakes and Vulture can help you with that.
Pyflakes is a passive code checker; it parses the code without executing it, so it won't break anything. It points out variable conflicts and, in contrast to other checkers, it doesn't complain about code style (we have black for that and more).
Vulture finds dead code: unused variables, functions and imports. But doesn't Pyflakes include this? Not exactly, because Pyflakes follows the principle of trying as hard as possible to avoid false positives. Vulture, on the other hand, adds to each warning a percentage of confidence. In Python is hard to tell when some function is unused, because it's a dynamic language, and in most cases, Pyflakes doesn't warn you about them.
Output comparison:
jendrikseipp
/
vulture
Find dead Python code
Tracking dependencies with pipreqs
Lastly, if you want your project to be used or modified by other programmers, it is better if they can install the dependencies directly, instead of installing them one by one, each one after a module not found error. For this purpose you have to add a requirements.txt file to your project.
You could do it manually (but that's not fun) or use pip freeze, but that writes all your installed packages, many more than necessary. Instead, using pipreqs, a requirements.txt file is generated with only the packages that your project uses.
Pipreqs example:
Now if someone clones your project, they can just use pip install -r requirements.txt and the dependencies will be installed.
Conclusion
I hope you find some of these as useful as I did. I'm pretty sure there are other great tools out there to use in Python projects. Do you know any? Please share them in the comments!
Recommended reading
Top comments (4)
Really a nice post @miguelmj 👏
But I'd suggest - instead of using so many different tools for fixing style issues (Black & Pep8) and code quality issues (PyFlakes), you can use DeepSource which internally uses all these tools and It is totally free for Open-Source ✨
Just one simple configuration file and you're good to go. It also gives you the option to Autofix most of the issues.
Do check it out and let me know what you think! 😁
Coming back 😄
I personally prefer tools that I can use locally, but that might be just a little mania of mine. It seems like a really useful tool and I will definitely learn to use it. Thanks again! 😉
Thanks for the recommendation! I will definitely check out when I have the opportunity and come back to comment on them. 😁
Thanks a lot, Amelia! I'm glad you find it useful! ^^