Stories about Software


Secrets of Maintainable Codebases

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, have a look at the tech debt quantification features of the new NDepend version.

You should write maintainable code.  I assume people have told you this, at some point.  The admonishment is as obligatory as it is vague.  So, I’m sure, when you heard this, you didn’t react effusively with, “oh, good idea — thanks!”

If you take to the internet, you won’t need to venture far to find essays, lists, and stack exchange questions on the subject.  As you can see, software developers frequently offer opinions on this particular topic.  And I present no exception; I have little doubt that you could find posts about this on my own blog.

So today, I’d like to take a different tack in talking about maintainable code.  Rather than discuss the code per se, I want to discuss the codebase as a whole.  What are the secrets to maintainable codebases?  What properties do they have, and what can you do to create these properties?

In my travels as a consultant, I see a so many codebases that it sometimes seems I’m watching a flip book show of code.  On top of that, I frequently find myself explaining concepts like the cost of code ownership, and regarding code as, for lack of a better term, inventory.  From the perspective of those paying the bills, maintainable code doesn’t mean “code developers like to work with” but rather “code that minimizes spend for future changes.”

Yes, that money includes developer labor.  But it also includes concerns like deployment effort, defect cycle time, universality of skills required, and plenty more.  Maintainable codebases mean easy, fast, risk-free, and cheap change.  Here are some characteristics in the field that I use when assessing this property.  Some of them may seem a bit off the beaten path.

Read More


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


Managing Code Analysis Statistics with the NDepend API

Editorial Note: I originally wrote this post for the NDepend blog.  You can check out the original here, at their site.  Also, NDepend just released a new version that addresses tech debt extensively — check it out while you’re there!

If you’re familiar with NDepend, you’re probably familiar with the Visual Studio plugin, the out of the box metrics, the excellent visualization tools, and the iconic Zone of Uselessness/Zone of Pain chart.  These feel familiar to NDepend users and have likely found their way into the normal application development process. NDepend has other features as well, however, some of which I do not necessarily hear discussed as frequently.  The NDepend API has membership in that “lesser known NDepend features club.”  Yes, that’s right — if you didn’t know this, NDepend has an API that you can use.

You may be familiar, as a user, with the NDepend power tools.  These include some pretty powerful capabilities, such as duplicate code detection, so it stands to reason that you may have played with them or even that you might routinely use them.  But what you may not realize is the power tools’ source code accompanies the installation of NDepend, and it furnishes a great series of examples on how to use the NDepend API.

NDepend’s API is contained in the DLLs that support the executable and plugin, so you needn’t do anything special to obtain it.  The NDepend website also treats the API as a first class citizen, providing detailed, excellent documentation.   With your NDepend installation, you can get up and running quickly with the API.

Probably the easiest way to introduce yourself is to open the source code for the power tools project and to add a power tool, or generally to modify that assembly.  If you want to create your own assembly to use the power tools, you can do that as well, though it is a bit more involved.  The purpose of this post is not to do a walk-through of setting up with the power tools, since that can be found here.  I will mention two things, however, that are worth bearing in mind as you get started.

  1. If you want to use the API outside of the installed project directory, there is additional setup overhead.  Because it leverages proprietary parts of NDepend under the covers, setup is more involved than just adding a DLL by reference.
  2. Because of point (1), if you want to create your own assembly outside of the NDepend project structure, be sure to follow the setup instructions exactly.

A Use Case

I’ve spoken so far in generalities about the API.  If you haven’t already used it, you might be wondering what kinds of applications it has, besides simply being interesting to play with.  Fair enough.

One interesting use case that I’ve experienced personally is getting information out of NDepend in a customized format.  For example, let’s say I’m analyzing a client’s codebase and want to cite statistical information about types and methods in the code.  Out of the box, what I do is open Visual Studio and then open NDepend’s query/rules editor.  This gives me the ability to create ad-hoc CQLinq queries that will have the information I need.

But from there, I have to transcribe the results into a format that I want, such as a spreadsheet.  That’s fine for small projects or sample sizes, but it becomes unwieldy if I want to plot statistics in large codebases.  To address this, I have enlisted the NDepend API.

Read More


Static Analysis Isn’t Just for Techies

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, download a trial of NDepend and give it a spin.

I do a lot of work with and around static analysis tools.  Obviously, I write for this blog.  I also have a consulting practice that includes detailed codebase and team fact-finding missions, and I have employed static analysis aplenty when I’ve had run of the mill architect gigs.  Doing all of this, I’ve noticed that the practice gets a rap of being just for techies.

Beyond that even, people seem to perceive static analysis as the province of the uber-techie: architects, experts, and code statistics nerds.  Developing software is for people with bachelors’ degrees in programming, but static analysis is PhD-level stuff.  Static analysis nerds go off, dream up metrics, and roll them out for measurement of developers and codebases.

This characterization makes me sad — doubly so when I see something like test coverage or cyclomatic complexity being used as a cudgel to bonk programmers into certain, predictable behaviors.  At its core, static analysis is not about standards compliance or behavior modification, though it can be used for those things.  Static analysis is about something far more fundamental: furnishing data and information about the codebase (without running the code).  And wanting information about the code is clearly something everyone on or around the team is interested in.

To drive this point home, I’d like to cite some examples of less commonly known value propositions for static analysis within a software group.  Granted, all of these require a more indirect route than, “install the tool, see what warnings pop up,” but they’re all there for the realizing, if you’re so inclined.  One of the main reasons that static analysis can be so powerful is scale — tools can analyze 10 million lines of code in minutes, whereas a human would need months.

Read More


4 Ways Custom Code Metrics Make a Difference

Edit: I originally wrote this post for the NDepend blog.  You can check out the original here, at their site.  While you’re there, download NDepend and give it a try.  If you like static analysis, you’ll find yourself hooked.

One of the things that has surprised me over the years is how infrequently people take advantage of customizable code metrics.  I say this not from the perspective of a geek with esoteric interest in a subject, wishing other people would share my interest.  Rather, I say this from the perspective of a business man, making money, and wondering why I seem to have little competition.

As I’ve mentioned before, a segment of my consulting practice involves strategic code assessments that serve organizations in a number of ways.  When I do this, the absolute most important differentiator is my ability to tailor metrics to the client and specific codebases on the fly.  Anyone can walk in, install a tool, and say, “yep, your cyclomatic complexity in this class is too high, as evidenced by this tool I installed saying ‘your cyclomatic complexity in this class is too high.'”  Not just anyone can come in and identify client-specific idiosyncrasies and back those findings with tangible data.


But, if they would invest some up-front learning time in how to create custom code metrics, they’d be a lot closer.

Being able to customize code metrics allows you to reason about code quality in very dynamic and targeted terms, and that’s valuable.  But you might think that, unless you want a career in code base assessment, that value doesn’t apply to you.  Let me assure you that it does, albeit not in quite as direct way as it applies to me.

Custom code metrics can help make your team better, and they can do so in a variety of ways.  Let’s take a look at a few.

Read More