Prospector

I consider myself one of the subset of developers who see software development as craftsmanship. Quality matters.

This was not always the case; early on in my career, I was very much of the mentality of “If it works, it ships” or the ever present excuse “But Does It Work?”. And for a time, when I was the lone developer of my own department, it worked. Sure there were pleanty of times where I went into a codebase I had written and had no idea what my past self had written while on a caffeine binge, but it just took me some time to figure it out and reason about it; I set my own deadlines anyway, so what was a few more days or hours regroking code I had written.

It wasn’t until I had my first employee in my department that I began to come to a to the realization that programming languages were languages not meant to just to communicate intent to computers, but often more importantly to communicate intent to other developers. I couldn’t just create my own words and rules in english and expect others to follow them. Shout-out to Jimmy Zelinskie, that employee who showed me the reasons why Quality Matters.

I quickly came to the realization that the larger the team, the more important code quality and following conventions and styleguides was. Luckily for me, python has a set of styleguides and rules to follow. At the most basic level, you have PEP8, which most people know and follow. Most editors will even help you out so you can write pep8 compliant code.

Following the trend that larger teams mean higher standards for code quality, when I tried to follow that pattern out to writing my first few open source projects, I was terrified to show my code to the world. “What if I am doing it wrong” or “What if this makes me look stupid”, questions that I now know every developer goes through, plagued me. I looked around at all of these other open source projects and I saw a few things that helped alleviate my fears; badges.

As a tangent, I understand that my obsession with code badges on repos is silly and most of them are empty proxy metrics for code quality. Things like coverage cyclomatic complexity scores are great to see at a glance, and convey stability and reliability, but are easily gamed metrics if they are the true measuring stick of quality. Code readibility is the most important metric of code quality, and that takes a developer reading your code and easily understanding your intent to grade it, not some automated script. But in this case badges, and my obsession with them, helped at least superficially get over my fear of publishing code.

When I speak about badges, I mean: These little pill things people put at the time of their README.md to show some stats about their repo. The one that intrigue me most, is this Health badge as shown above on my first open source project: py-mailinator.

The health badge is a metric maintained by landscape.io. It was generated on code push, it would pull in your code and run a suite of python code qualitiy tools against it. It would generate a list of messages from things like Code Smells, Style Guide Infractions, Erroneous Code and give a grade to your code. The report looks something like

This worked great for my python code, especially when working on an open source project by myself. I would commit some code, check the problems with it, and correct them; it was my automatic code review for python standards. My problem with Landscape came when I wanted to use the tool on non-open-source projects. My personal projects I wanted to keep private, but still keep all of the wonderful reports and high code quality.

Enter Prospector. Prospector, is the open source tool built by Landscape that does all of the code reporting that powers their service. Under the hood, it just runs other open source code quality tools such as:

• pep8
• pylint
• pyflakes
• mccabe complexity
• dodgy
• pydocstyle
• pyroma
• vulture
• frosted

It has a single runner for all of the above, and easy to use YAML configuration file that allows you to configure which tools to use, and which options on those tools to set. It is a one stop shop for all things python code quality.

The docs are quite extensive, and go over the different uses and how to set it up as a CI tool, so you can fail your build on quality infractions. It has a few modes of strictness:

• verylow
• low
• medium
• high
• veryhigh

as well as the flags test-warnings and doc-warnings to enabled quality checking on tests and comments/doc strings.

I like to start projects on veryhigh, and turn off the warnings that no longer serve me as they come up. Warning, the veryhigh stictness level can be very pedantic, and will slow you down until you are used to writing very compliant code the first time around. I would recommend starting with the default strictness of medium, cleaning up all the errors, testing it with high, see how many flags are introduced, and following the path of least resistance.

Prospector is now a default part of all of my python projects build tools and CI process. For solo development it has defiantly pushed me strongly in the direction of better code quality.