How to Evaluate Software Quality from Source Code
Editorial note: I originally wrote this post for the Stackify blog. You can check out the original here, at their site. While you’re there, take a look at their Retrace offering that gives you everything you need to track down production issues.
I’ll understand if you read the title of this post and smirked. I probably would have done so, opening it up only to see what profound wisdom awaited me. Review the code, Captain Obvious.
So yes, rest assured, I understand the easy assumption that one can ascertain a codebase’s quality by opening it up and starting to review it. But what does this really tell you? What comes out of this activity? Simply put, your opinion of the codebase’s quality comes out of this activity.
I actually have a consulting practice doing custom static analysis on client codebases. I help managers and executives make strategic decisions about their applications. And I do this largely by treating their code as data and building numerically based cases.
Initially, the idea for this practice arose out of some observations I’d made a while back. I watched consultants tasked with critical evaluations of codebases, and I found that they did exactly what I mentioned in the first paragraph. They reviewed it, operating from the premise, I’m an expert, so I’ll record my anecdotal impressions and offer them as evidence. That put a metaphorical pebble in my shoe and bothered me. So I decided to chase a more empirical concept of code quality with my practice.
Don’t get me wrong. The proprietary nature of source code and outcome data in the industry makes truly scientific experiments difficult. But I can still automate the inquiries and use actual, relative data to compare properties. So from that perspective, I’ll offer you more data-driven ways to evaluate software quality from source code.
Aug
29
By Erik Dietrich
Is There a Correct Way to Comment Your Code?
Category: Language Agnostic Tags: Clean Code, Comments, NDepend | 50 Comments
Editorial note: I originally wrote this post for the NDepend blog. You can check out the original here, at their site. While you’re there, take a look at all of the visualizations and metrics that you can get about your codebase.
Given that I both consult and do a number of public things (like blogging), I field a lot of questions. As a result, the subject of code comments comes up from time to time. I’ll offer my take on the correct way to comment code. But remember that I am a consultant, so I always have a knee-jerk response to say that it depends.
Before we get to my take, though, let’s go watch programmers do what we love to do on subjects like this: argue angrily. On the subject of comments, programmers seem to fall roughly into two camps. These include the “clean code needs no comments” camp and the “professionalism means commenting” camp. To wit:
And then, on the other side:
Things would probably go downhill from there fast, except that people curate Stack Overflow against overt squabbling.
Splitting the Difference on Commenting
Whenever two sides entrench on a matter, diplomats of the community seek to find common ground. When it comes to code comments, this generally takes the form of adages about expressing the why in comments. For example, consider this pithy rule of thumb from the Stack Overflow thread.
Jeff Atwood has addressed this subject a few different times.
And so, as with any middle ground compromise, both entrenched sides have something to like (and hate). Thus, you might say that whatever consensus exists among programmers, it leans toward a “correct way” that involves commenting about why.
Read More