Stories about Software


Measure Your Code to Get Back on Track

Editorial Note: I originally wrote this post for the NDepend blog.  You can check out the original here, at their site.

When I’m called in for strategy advice on a codebase, I never arrive to find a situation where all parties want to tell me how wonderfully things are going.  As I’ve mentioned before here, one of the main things I offer with my consulting practice is codebase assessments and subsequent strategic recommendations.

Companies pay for such a service when they have problems, and those problems drive questions.  “Should we scrap this code and start over, or can we factor toward a better state?”  “Can we move away from framework X, or are we hopelessly tied to it?”  “How can we evolve without doing a forklift upgrade?”

To answer these questions, I assess their code (often using NDepend as the centerpiece for querying the codebase) and synthesize the resultant statistics and data.  I then present a write-up with my answer to their questions.  This also generally includes a buffet of options/tactics to help them toward their goals.  And invariably, I (prominently) offer the option “instrument your code/build with static analysis to raise the bar and prevent backslides.”

I find it surprising and a bit dismaying how frequently clients want to gloss over this option in favor of others.

Using the Observer Effect for Good

Let me digress for a moment, before returning to the subject of preventing backslides.  In physics/science, experimenters use the term “observer effect” to describe an experimental problem.  This occurs when the act of measuring a phenomenon changes its behavior, inextricably linking the two.  This presents a problem, and indeed a paradox, for scientists.  The mechanics of running the experiment contaminate the results of the experiment.

To make this less abstract, consider the example mentioned on the Wikipedia page.  When you use a tire pressure gauge, you measure the pressure, but your measurement lets some of the air out of the tire.  You will never actually know what, exactly, the pressure was before you ran the experiment.

While this creates a problem for scientists, businesses can actually use it to their advantage.  Often you will find that the simple act of measuring something with your team will create improvement.  The agile concept of “big, visible charts” draws inspiration from this premise.

In discussing this principle, I frequently cite a dead simple example.  On a Scrum team, the product owner has ultimate responsibility for making decisions about the software’s behavior.  The team thus needs frequent access to this person, despite the fact that product owners often have many responsibilities and limited time.  I recall a team who had trouble getting this access, and put a big piece of paper on the wall that listed the number of hours the product owner spent with the team each day.

The number started low and improved noticeably over the course of a few weeks with no other intervention at all.

Read More


Automate Your Documentation

Editorial Note: I originally wrote this post for the SmartBear blog.

Few things, I’d say, strike boredom into the developer heart faster than the subject of documentation.  Does anyone out there really just love wrapping up development on a feature and then cranking out a Word document with a bunch of screen shots and step by step instructions.  Or, perhaps you fancy the excitement of pasting a legal header above a class you’ve just written, and then laboriously documenting all of methods, variables, and function parameters in the class?  If not that, how about the thrill of going back and updating comments that no longer make sense after the code has changed?

I suspect I don’t have a lot of takers at this point.

Documentation is boring, at least for the overwhelming majority of us.  After you’ve built a thing, you want to go build another thing — not rehash in laborious detail what you just did.  And yet, documentation is essential for communicating across time and teams to other people.  Your users will need documentation.  Future maintenance programmers need documentation.  Unless you’re going to be around in perpetuity to handle all that comes, you need to leave some sort of persistent knowledge transfer vehicle.

But that doesn’t mean it has to be tedious, repetitive, or boring.

Repetitive labor offers a certain counter-intuitive appeal, since it creates a “pain is gain” feeling of diligence and accomplishment when complete  But don’t be fooled.  People make many sloppy mistakes when doing repetitive tasks and drudgery is a terrible use of company money when you’re collecting a salary as a knowledge worker.  As people in the software industry, we earn a living automating grunt work out of existence, so let’s take a look at how we can help ourselves when it comes to documentation.

Read More


What Is Reasonable to Expect from Your IDE?

Editorial Note: I originally wrote this post for the SmartBear blog.  You can check out the original here, at their site.

If you’re a software developer, there’s a decent chance you’ve been embroiled in the debate over integrated development environments (IDEs) versus text editors.  Users of IDEs will tell you that they facilitate productivity to a degree that makes them indispensable, whereas users of text editors will tell you that the IDEs are too big and bloated, and hide too much of the truth of what’s happening from you.  In some cases, depending on the tech stack and personalities involved, this can become a pretty serious debate.

I have no intention whatsoever of wading into the middle of that debate here today.  Rather, I’d like to tackle this subject from a slightly different angle.  Let’s take at face value that text editors are comparably feature-poor but nimble, and that IDEs are comparably feature-rich but laden with abstraction.  Framed as a tradeoff, then, it becomes clear that realizing the benefits of one choice is critical for justifying it.  To put it more concretely, if you’re going to incur the overhead of an IDE, then it had better be doing you some good.

With this in mind, what should you expect from an IDE?  What should it do in order to justify its existence, and what should be a deal breaker if missing?   Let’s take a look at what’s reasonable to expect from IDEs.

Read More


Should You Review Requirements and Design Documents?

Editorial Note: I originally wrote this post for the SmartBear blog.  You can check out the original here, at their site.  While you’re there, have a look around at posts and knowledge from other authors.

I remember working in a shop that dealt with medical devices some years back.  I can’t recall whether it was the surrounding regulatory requirements or something about the culture at this place, but there was a rule in place that required peer review of everything.

Naturally, this meant that all code was reviewed, but it went beyond that and extended to any sort of artifact produced by the IT organization.  And, since this was a waterfall shop, that meant review (and audit-trails of approval) of the output of the requirements phase and the design phase, which meant requirements and design documents, respectively.  I can thus recall protracted meetings where we sat and soberly reviewed dusty documents that made proclamations about what “the system” shall and shan’t do.  We also reviewed elaborate sequence, flow, hierarchy, and state design artifacts that were probably obsolete before we even reviewed them.

If I make this activity sound underwhelming in its value, that’s because I routinely felt underwhelmed by its value.  It was a classic case of process over common sense, of ceremony over pragmatism.  Everyone’s attention wandered, knowing that all bets would be off once the development started.  Sign-offs were a formality — half-hearted and cursory.

But is it worth throwing the baby out with the bathwater?  Should the fact that waterfall shops waste time on and around these documents stop you from producing them and subsequently reviewing them?  Is it worth reviewing requirements and design documents?


Read More


Why Automate Code Reviews?

Editorial Note:  I originally wrote this post for the SubMain blog.  You can check out the original here, at their site.  This is a new partner for whom I’ve started writing recently.  They offer automated code review and documentation tooling in the .NET space, so if that interests you, I encourage you to take a look.

In the world of programming, 15 years or so of professional experience makes me a grizzled veteran.  That certainly does not hold for the work force in general, but youth dominates our industry via the absolute explosion of demand for new programmers.  Given the tendency of developers to move around between projects and companies, 15 years have shown me a great deal of variety.


Perhaps nothing has exemplified this variety more than the code review.  I’ve participated in code reviews that were grueling, depressing marathons.  On the flip side, I’ve participated in ones where I learned things that would prove valuable to my career.  And I’ve seen just about everything in between.

Our industry has come to accept that peer review works.  In the book Code Complete, author Steve McConnell cites it, in some circumstance, as the single most effective technique for avoiding defects.  And, of course, it helps with knowledge transfer and learning.  But here’s the rub — implemented poorly, it can also do a lot of harm.

Today, I’d like to make the case for the automated code review.  Let me be clear.  I do not view this as a replacement for any manual code review, but as a supplement and another tool in the tool chest.  But I will say that automated code review carries less risk than its manual counterpart of having negative consequences.

Read More