Stories about Software


What It Really Means to Niche Down

It’s been a rather frustrating few weeks for me, at least in terms of getting things done at home.  One of the cables on my garage door got off of its track somehow, and my time is at a premium, so I set about hiring someone to fix it.  I went onto Angie’s List to see if I could find a contractor that specialized in solving this sort of problem.

Looking for that was probably stupid, however.  I realized my mistake when I got onto the site and did a search for contractors.  I tried searching for terms like “fixes garage doors” and got empty results back.  Stymied, I started looking at contractor profiles and seeing that they really didn’t match in any way even remotely like that.  Here’s what a typical one looked like.

  • Extremely proficient in hammer, table saw, drill driver, and crowbar.
  • 5 years of experience cutting cables, tying knots, and winding metal cables around spring-loaded spools.
  • Limited experience with reciprocating saw and lathe.
  • Regularly determines the correct situation for using a screw versus a nail.
  • Strong preference for DeWalt tools.
  • Capable of carrying tools in a bag, box, or wheeled assembly as dictated by the job.
  • Excellent oral and written communication skills.

*Smacked forehead*  Of course!  I’d been going about this all wrong.  I was looking for an expert to solve my problem, when what I really needed to do was spend a lot of time learning the minutiae of what exact skills, tools, and techniques were necessary to solve that problem.  Once I’d spent a few days doing that, I could then make a still ill-informed guess as to which contractor’s experience might prove relevant to my situation.

That’s exactly what I did, and, though you’d assume this would go well, somehow, it didn’t.  The first guy said he had a lot of experience with steel cables, things that twist, and larger fixtures.  As a bonus, he expressed an intimate knowledge of how water would impact the garage door apparatus.  I had no idea how this was relevant, but he sounded like he knew what he was doing, so I hired him.  After two days, I came and found that he hadn’t fixed the door, but he had installed a sink that was blocking my car in.  When I demanded to know why he’d done this, he confessed that he was really more of a plumber, but that he wanted to learn about garage doors and just assumed that they were more or less the same thing.

Sink in Garage

The next guy didn’t build anything that blocked my car in.  As a matter of fact, he didn’t build anything at all.  He just came in for a few days, laid all kinds of screws, nuts, bolts, and magnets on the ground, and then proceeded to arrange, re-arrange, and re-re-arrange them ad nauseum.  Each time he’d do it, he’d squint at the broken garage door apparatus and mutter to himself about it being important to have the right organizational framework to tackle this problem.  When I finally let him go after a few days, he’d managed to build a small pyramid out of 2 inch screws.  I’m not going to lie; it was impressive.  But it was also useless.

Knowing that this was stupid, I did what any reasonable person would do.  Instead of hiring someone to solve my problem, I hired someone that could both understand what I was trying to do and who could also make sense of all of these contractor profiles.  All it cost me was an extra 20% of the job total.

Read More


Dealing with Legacy Code for Developers: Managing your Manager

Editorial note: I originally wrote this post for the NDepend blog.  Click here to check out the original, on their site.  While you’re there, take a look around at the other posts and the offering.

Here’s a campfire horror story of legacy code that probably sounds at least somewhat familiar.

One day, your manager strolls by casually, sipping a cup of coffee, and drops a grenade in your lap.  “Do you think we can add an extra field to the customer information form?”  Sure, it may sound innocuous to an outsider, but you know better.

The customer information form is supported by something written almost a decade ago, by a developer long departed.  Getting that data out of the database and onto the form prominently features a 60,000 line class called DataRepositoryManagerHelper and it also makes use of a gigantic XML file with odd spacing and no schema.  Trying to add a field to that form casts you as Odysseus, navigating between Scylla and Charybdis.  In fact, you’re pretty sure that author of the legacy code made it necessary for the assigned developer to cut off and sacrifice a finger to get it working.


Aware of all of this, you look at your manager with a mix of incredulity and horror, telling her that you’ll need at least 6 weeks to do this.  Already swirling around your mind is the dilemma between refactoring strategically where you can and running exhaustive manual testing for every character of the source code and XML that you change.  It’s now her turn to look incredulous and she says, “I’m just asking for a new field one one form.”  You’ve told her before about this, and she’s clearly forgotten.  You’re frustrated, but can you really blame her?  After all, it does sound a little crazy.

The Nature of Legacy Code

I’ve talked in the past about legacy code as code that developers are afraid to touch (which I correlate closely with Michael Feathers’ definition as “code without tests”).  If you accept this definition as axiomatic, there’s a critical implication here: legacy code creates a disconnect between the developers and everyone else.

As “everyone else” you see a form that needs a conceptually simple tweak.  As a developer, you see a mythological monster that threatens to rip your digits from your body; you see something that inspires fear.  And, while the bodily fear I’m referring to is an exaggeration, the visceral fear of unknown and lack of understanding is not.  Management is asking you to do something it thinks of as simple, and your head is flooded with an overwhelming number of possibilities as to how this could all go quite wrong.  And, worst of all, it’s really hard to explain this without it sounding as though you’re making excuses, being lazy, or being melodramatic.

If you want to understand how to manage expectations around the legacy code in your codebase, understanding this expectation mismatch is critical.  From that starting point, let’s look at some things you can do to make your life easier.

Read More


Creating Your Code Review Checklist

Editorial Note: I originally wrote this post for the SmartBear blog.  You can read the original here, at their site.  There’s a lot of other good stuff over there as well, so look around.

In any line of work, there are a number of rites of passage by which you can mark your career and feel good about milestones achieved.  Programming is no different.

Think back to the first time you were asked to perform a code review.  How exciting! (Though you probably laugh at your younger self now for being excited to review code.)  You spent time as the newest programmer in the organization, under the impression that code reviews were something done to you rather than by you, but now you have confirmation that your opinion is valued.

If you’re anything like me, the first thing you did in such a situation was to scramble to Google and start punching in things like, “how to conduct a code review,” “code review checklist,” or “code review best practices.” Being asked to weigh in on someone’s code is a lot of responsibility, and who wants to screw that up?  In such a Google search, you’ll probably find recommendations that steer you toward a list like this:

  • Does every method have an XML comment?
  • Do classes have a copyright header?
  • Do fields, methods, and types follow our standard naming convention?
  • Do methods have too many parameters?
  • Are you checking validity of method parameters?
  • Does the code have “magic” values instead of named constants?

Seems pretty reasonable, right?  If we brainstormed for an hour or two, we could probably flesh this out to be a comprehensive list with maybe 100 items on it.  And that’s what a lot of code review checklists look like — large lists of things for reviewers to go through and check.  So code review becomes an activity reminiscent of a line supervisor inspecting factory equipment with a clipboard.


There are two problems with this.

  1. You can’t keep 100+ items in your head as you look at every method or clause in a code base, so you’re going to have to read the code over and over, looking for different things.
  2. None of the checks I listed above actually require human intervention. They can all be handled via static analysis.

Read More


Bridging the Communication Gap Between Developers and Architects

Editorial Note: I originally wrote this post for the NDepend blog.  Go check out the original here, at their site.  While you’re there, have a look around at the other posts and at NDepend itself.

If you want to set off a ceaseless, spirited discussion, ask a roomful of people what makes some music good and other music bad.  The opinions are likely to be as spirited as they are diverse, with, perhaps, good points to be had.  But consensus is unlikely.


If you want to see a similar dynamic in the software development world, ask a roomful of software developers what a software architect is.  What makes a person an architect?  Does the architect write code?  What kinds of decisions should an architect make?  What is the relationship between architects and developers?  Do developers report to the architect, or is it a “dotted line” reporting relationship?  Maybe they’re peers?  Do architects need to have a lot of domain knowledge?  Do architects need to be the best programmers (or at least have been at some point)?  You get the idea.

Go out and observe enough software shops in action, and you will see every different imaginable answer to these questions in every possible combination.  This fact alone lays seeds for myriad communication complexities between developers and architects.  In any shop, a developer is more or less a developer.  But the architect role varies widely and, as developers move from company to company, this creates confusion.

Before going further down that path, let’s consider some things that are often true of a software architect.  And, I say “often true” because, as I just pointed out, the definition is fluid enough that it’s hard to pin things down definitively the way we might say, “software developers write computer programs.”

  • Architects tend to be the ones to make “big picture decisions” (which language/database/framework will we use?)
  • Architects tend to have more tenure at companies and more industry experience.
  • Architect tends to be a leadership role, meaning they supply either thought leadership, org chart leadership, technical leadership, or some combination.
  • Architects tend to have more face time with “the business” than developers.

What do all of these tendencies mean?  Well, simply put, they mean that architects have somewhat of a different area of focus than software developers.  Developers concern themselves primarily with the tactical, and architects concern themselves mainly with the strategic.  The concept of tactics versus strategy can be (perhaps over-) simplified to the idea that strategy is the “what” and tactics are the “how.”  If it comes to your personal finance, “diversification” may be the strategy and “spend X amount on stocks, Y on bonds, and Z on real estate” may be your tactics.


Read More


Are Your Arguments Falsifiable?

Editorial note: I’d like to clarify something here upon re-reading this post.  When I refer to not engaging comments, I’m talking about in other venues (other blogs than mine, social media, and sites like reddit).  On this blog, I do my best to engage with everyone that takes the time to leave a comment, regardless of its contents.  Please don’t read this as any sort of deterrent to commenting — keep ’em coming!

These days, I’m writing for 6 blogs besides my own.  All of the posts get announced on social media and some of them wind up on commentary sites like Hacker News or Reddit, which means that there’s a lot of surface area, so to speak, for comments.  I make a good faith effort to respond, but I must confess that my response/comment ratio is declining amidst lots of writing and my consulting practice.

My failure to respond to a comment tends to fall into one of three categories.

  1. Never saw it.
  2. Saw it, made a mental note to come back and respond later, but “later” never came.
  3. /Sigh/

It’s this last, and admittedly enigmatic category, about which I’d like to talk today.

The Ones that Make Me Sigh

You’re probably thinking here that I’m talking about the occasional piece of random insult or profanity.  Perhaps someone leaves a comment on the site saying, “you’re a #&%$ing idiot.”  But no, it’s not that.  A comment like that (which is actually refreshingly rare) doesn’t induce much reaction in me one way or the other.  Just a half amused, half bemused, “well, okie dokie.”


The ones that make me sigh are comments that I think of as “specious definers.”  They are thoughts offered as correction and conversation advancement, but that wind up falling flat in a subtle way.  Make no mistake — these are thoughts offered in earnest, and I’m not complaining about tone or being corrected or anything like that.  Rather, I’m lamenting that I read, re-read, and re-read again, and realize that what I’m looking at is a near tautology.  It’s a non-falsifiable closed loop, to borrow slightly from Karl Popper.

Let’s get out of generalities and deal with a couple of examples.  Please note at this point that I’m operating off of admittedly imperfect memory, and thus paraphrasing.  I don’t know where either of these examples is nor even in what medium it was offered.  But please believe that I have no real interest in distortion here — the critiques are not objectionable.

Read More