Month: October 2012

// Comments on Comments

/*

We spend little or no time teaching programmers how to write good comments.

This is surprising, when you consider how often “total lack of comments” or “poor comments” are cited as evidence that certain modules (or the programmer who wrote them) are the worst thing that ever happened to the technoverse.

Comments shouldn’t leave you–or anybody else–mystified. :-) Image credit: xkcd

I happen to think that there are much yuckier tech things than poor or missing comments in code. But I still think our general level of comment proficiency is lower than it should be.

Here is my attempt to raise the bar a little.

Why We Comment

Sooner or later, most interesting programming problems require a sophisticated mental model of a problem. Building these models is hard work, and once we have them, we are paid to share with our team (or our future selves).

The best way to share mental models with other engineers is Continue reading →

Tech Debt, Leverage, and Grandma’s Envelope

In my previous posts about tech debt, I focused on how we can help organizations remember their debts, and on understanding how tech debts are funded and paid back.

Photo credit: Friends of the Earth International (Flickr)

Photo credit: Friends of the Earth International (Flickr)

These topics hit a raw nerve with coders and testers. Those in the trenches often feel very keenly the cost of doing things in a messy way, and it’s common for them to worry that others don’t “get it.”

They’re not wrong to worry.

However, today I’d like to put on my executive hat and discuss tech debt from a perspective that code jockeys sometimes miss, because blindness is not just an executive disease.

Debt as Leverage

When you hear the word “leverage” in business circles, people are talking about debt: a “highly-leveraged” firm is one financing large portions of its strategy through debt; “leveraged buyouts” are transactions where the buyers borrow vast sums of money from a risk-taking lender to take a company private.

Technogeeks (like me): business people are not dumb. Why did they settle on this metaphor of debt as leverage?

The answer is that debt can allow a company to concentrate enough capital in a short enough timeframe to make high-impact strategic moves that would otherwise be impossible. It’s an enabler and multiplier.

Another take on leverage. Image credit: xkcd.

Debt is a fundamental machine in the business toolkit, just as levers are a fundamental machine for mechanical engineers. Almost all businesses use debt to some extent. If a CEO can borrow capital at 9% and produce 12% ROI with it, and Continue reading →

How Enums Spread Disease — And How To Cure It

Poorly handled enums can infect code with fragility and tight coupling like a digital Typhoid Mary.

Say you’re writing software that optimizes traffic flow patterns, and you need to model different vehicle types. So you code up something like this:

vehicle_type.h

enum VehicleType {
    eVTCar,
    eVTMotorcycle,
    eVTTruck,
    eVTSemi,
};

Then you press your enum into service:

route.cpp

if (vehicle.vt == eVTSemi || vehicle.vt == eVTTruck) {
    // These vehicle types sometimes have unusual weight, so we 
    // have to test whether they can use old bridges...
    if (vehicle.getWeight() > bridge.getMaxWeight()) {

Quickly your enum becomes handy in lots of other places as well:

if (vehicle.vt == eVTMotorcycle) {
    // vehicle is particularly sensitive to slippery roads

And…

switch (vehicle.vt) {
case eVTTruck:
case eVTSemi:
    // can't use high-occupancy/fuel-efficient lane
case eVTMotorcycle:
    // can always use high-occupancy/fuel-efficient lane
default:
    // can only use lane during off-peak hours
}

Diagnosis

The infection from your enum is already coursing through the bloodstream at this point. Do you recognize the warning signs?

  • Knowledge about the semantics of each member of the enum are spread throughout the code.
  • The members of the enum are incomplete. How will we account for cranes and bulldozers and tractors and vans?
  • Semantics are unsatisfying. We’re saying cars are never gas guzzlers or gas savers; what about massive old steel-framed jalopies and tiny new hybrids?

A vehicle that challenges our tidy enum. Photo credit: Manila Imperial Motor Sales (Flickr)

The infection amplifies when we want to represent the enum in a config file or a UI. Now we need to Continue reading →

Baby Steps

Film poster, displayed under fair use as documented on Wikimedia Commons.

If you’ve seen the delightful comedy movie, What About Bob?, you are no doubt smiling at my title.

Bob is a neurotic and thoroughly irritating patient who depends on his psychotherapist for lots of emotional strokes and life coaching. He ingratiates himself with the therapist’s family and gets himself invited to be their guest on a weekend getaway, against the protests of the therapist. He then proceeds to drive the therapist crazy.

One of Bob’s favorite phrases is “baby steps,” which captures the therapist’s advice to solve problems a little bit at a time, rather than in overwhelming chunks.

“Baby steps” is surprisingly good advice for many questions in software design. It doesn’t apply in all cases, but it applies far more often than it ends up being used.

The Purpose of Design

We create UML diagrams, personas, design docs, lo-fi mockups, and other artifacts to capture our architectural thinking because they provide us with a roadmap of sorts. We need to identify and steer to a consistent point of the compass if we want to produce complex artifacts that meet customer needs. The bigger and more diversified our teams get, and the more moving parts we’re orchestrating into our software, the more important this is.

However, all of these artifacts are means to an end. To whit: Continue reading →

On SEPs, Squirrels, and Meta Questions

In Douglas Adams‘ novel, Life, the Universe, and Everything, a spaceship lands in the middle of a stadium of screaming fans during a cricket match, and nobody notices. The ship doesn’t use a Klingon-style cloaking device to accomplish this amazing feat; instead, it is hidden by a “Somebody Else’s Problem” field, which operates on the principle that if something is perceived to be somebody else’s problem, the brain of onlookers will treat it as if it were invisible.

Adams was a sci-fi author, but I see applications of his metaphor in the day-to-day work of software engineering.

To one degree or another, we all exhibit inattentional blindness from time to time. And that can be a good thing. Being able to zero in on a particular block of code, to the exclusion of the guy sneezing or yawning in the next cube, is healthy. We don’t want to be like the dogs in Pixar’s Up!, who keep getting distracted by squirrels.

However, truly superb engineers have a capacity to see through the cloak of somebody else’s problem; they think simultaneously on multiple levels of abstraction. They tend to ask “meta questions” (judiciously) that poke at larger issues, broader contexts, or more distant time horizons. Not coincidentally,  Continue reading →