Project Summarizer - Why Was It Needed?

Summary¶

In my last article, I talked about taking a break from scenario testing the nested containers in the PyMarkdown project and just getting back to fixing simple issues. In this article, I talk about taking more of a break to upgrade one of the tools I use: Project Summarizer

Introduction¶

If a competent developer is talking honestly about their development prowess, the lion’s share of that prowess is because of the tools they use every day in their work. If a developer must stop and think about how to use the tools at their disposal, they often lose track of what they were thinking about. After a task- switch or context-switch like that, it can take up to half an hour to get back to where they were.

That is why good tools are important. The tools that a developer uses must be able to make the developer more efficient by keeping the developer in the moment and solving the problem that they are working on. Not in trying to figure out how to bend the tools they use to their needs.

What Is the Audience for This Article?¶

While detailed more eloquently in this article, my goal for this technical article is to focus on the reasoning behind my solutions, rather than the solutions themselves. For a full record of the solutions presented in this article, please consult the commits that occurred between 15 Feb 2022 and 20 Feb 2022.

What Makes A Good Tool?¶

From my experience, there are three types of tools that are useful for developer efficiency: editors, monitoring, and analysis. While there may be more tools from someone else’s point of view, those are the categories that I use.

Editors¶

The choice of an editor for a developer is very much a religious thing. For all intents and purposes, this is where the developer will live while they are writing their programs. As such, it needs to feel right to them. If it does not feel right to them, they will not be as efficient as with a “good” editor. And to be honest, the feel of an editor really does depend on the developer.

Take the editor vi. A standard of Linux systems since the beginning, it is a very capable editor, but one with a steep learning curve. However, I have known developers that can make the keys fly and just make the editor sing with their code changes. Then there are the families of editors, such as the JetBrains family of editors. Supporting a staggering twelve development environments, JetBrains is clearly a leader when it comes to development editors. In their case, they leverage a common look and feel, along with well tested development tools, to provide multiple native editors for twelve distinct languages. This works well because developers often use multiple languages, and with a JetBrains editor, you can switch languages without having to relearn large parts of the editor’s look and feel.

And that brings me to VSCode. At some point, Microsoft decided that they wanted to join the fray, and their answer was VSCode. Immensely popular with developers across many languages, it uses extensions and plugins to allow developers to customize their development experience to the way they want it. For example, on my instance of VSCode I have the Python extension and the Pylance extension enabled for writing Python, with Sourcery and Code Inspector to supply an instant analysis. I am currently narrowing down my favorite Git extension to one of two plugins, but VSCode is okay with me having both installed at the same time.

That is why I feel that the true reason VSCode is popular: because it is so configurable. As I mentioned at the top of this section, the choice of editors is a religious thing. If something is not working well for me, I can try new extensions to bring it more in line with my developer process. Basically, I can fine-tune the feel as much as I want to. And that is what makes VSCode such a powerful editor for me. I can write Bash scripts in it, Python modules in it, or C++ files. Each language with the same level of support as the other two.

The common thread here is that for an editor to be effective for a given developer, it must make them more efficient and not get in the way. And that means being very customizable.

Monitoring¶

Monitoring tools are often forgotten, but I believe that they are a major component of a developer’s toolbox. These tools are anything that allow the developer to examine and monitor their applications in action once they have been completed. Whether it is something as simple as having the Windows Task Manager application open in Summary View mode (go to Performance, right click on CPU, and select Summary View), or pairs of applications such as Linux’s top and watch df -h commands, these tools help the developer to decide if their applications are behaving properly.

And while it might not be a popular choice, I also throw Unit Testing and Scenario Testing into this part of the toolbox. Because these tests are actively examining the output of the application with various inputs, I feel that they are critical in determining if the application is performing as expected. Especially if these tests are paired with a solid Continuous Integration workflow, their monitoring of any external changes in the application are pivotal to the application’s success.

The common thread for these monitoring tools is that the monitoring tools must present the developer a solid look at the application, both the environment that it is executing in and how it is performing itself within that environment.

Analysis Tools¶

And finaly, there are the Analysis tools. These can often be the most controversial tools to talk about because of what they do: analyze how well the application measures against a given metric. These tools can include, but are not limited to:

• formatters that automatically change the style of the code to match a single style
• linters that scan the code for known errors or anti-patterns, and reporting them
• coding assistant that provides analysis within the editor
• summarizers that take a more complicated analysis and break it down into easier to digest bites

A good example of the formatter tool is Black. Used on the various projects that I work on; this formatter ensures that every line of Python is formatted in a single consistent manner. From their website:

Blackened code looks the same regardless of the project you’re reading. Formatting becomes transparent after a while and you can focus on the content instead.

And from experience, it is particularly good at achieving that goal. I do not find myself focusing on the formatting at all, because I know Black will pick that up.

In that same vein, the PyLint linting tool provides a useful tool for scanning for well-known issues in Python code. It does not have a great tag line like Black but provides useful indicators that help me write better Python code every day. I can honestly say that I have avoided a lot of coding issues simply by dealing with most PyLint warnings. Like my use of Black for formatting, my experience with PyLint allows me to write Python code without worrying about the nitty-gritty of the language. I have confidence that PyLint has my back when it comes to catching a lot of the commonly seen antipatterns.

Next up are the coding assistant tools. These are analyzers that are executed within the scope of the editors and supply near instant feedback. The reason that these tools are useful is that instead of waiting until the code is completed, these tools provide near-immediate feedback on what a developer is writing. I currently use Code Inspector to run a version of the PyLint checks as well as Sourcery.Ai for more insightful analyses. Both tools provide different insights while I am writing my Python code, but both are useful. And as those insights are being provided as I code, I can wait for a good breaking point, check out those insights, and determine how best to respond to them. It just works.

Why Can These Analysis Tools Be Controversial?¶

Just a note here. This is my opinion, from my experiences. The experiences of readers may vary from what I am about to say. Basically, read these next paragraphs with an open mind.

From my experience, software developers have a tough time removing themselves from the code that they write. As such, if you run an analysis on “their” code, they can feel that you are judging them, as they created the code. And people do not like being judged. Therefore, they would rather feel better and not analyze their code to see how it can be better.

Now, that is a loaded viewpoint, but I believe it is a fairly accurate one. Even I suffered from that tainted viewpoint of “my code is my me” in the early stages of my career. But after a while, I realized that while my code is an expression of myself, so are the tools that I can use to make that code better. However, that was not an easy step for me to take. It took about a decade for me to make that transition, and there were many times I moved one step forward only to follow that with two steps backward.

Finally, at one point, it was a conversation with a colleague that cemented by current view for me. When talking about code analysis tools and code coverage, he mentioned his skills as a carpenter. He mentioned that no one would have a problem if he came to a project with a new hammer or a different tool than expected if the results justify it. He then continued on that path and switched to software projects, where he saw many of his colleagues wince at his suggestion of a better tool or a separate way of approaching the process. He thought it was… er… stupid and silly. But that conversation is the one that finally got me cemented on my current way of thinking about analysis tools.

But not everyone is there. And it takes experience to know to walk that path.

Summarizer Tools¶

But what about summarizer tools?

To be blunt, I did not find any. And it was driving me nuts. I love having a short cycle between making changes and seeing their results. The shorter the better.

But when it came to Python tests via PyTest, the closest thing to a tool I had was to manually open the PyTest results page and look through there. The main console display would show me pass/fail easily enough, but it would not group them according to the file. That was only available by examining the HTML output. A similar pattern existed with Code Coverage. I would make a change, test it out, and then have to open the HTML coverage webpage to figure out if I had every line and path covered. I had to type those two URLs into the browser so often that I created a new script with the content:

start report\coverage\index.html
start report\report.html

But I knew there had to be a better way of doing things. I quickly came to one conclusion. I needed to write my own tool to summarize the analyses of other tools. I needed something I could run with every commit and between commits to give me immediate feedback on how I was doing.

And thus, Project Summarizer was born.

What is Next?¶

Having laid the groundwork for why I needed Project Summarizer, it was time for me to design it with good requirements in place. Stay tuned!

Like this post? Share on: Twitter ❄ Facebook ❄ Email