DaedTech

Stories about Software

By

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?

LotsLeftToDo

Read More

By

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.

Lifer

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

By

What a Software Audit Means for You

Editorial Note: I originally wrote this post for the SmartBear blog.  Check out the original, here, at their site.  While you’re there, have a look around at some of the other authors’ posts.

“We’re being audited.”

Now there’s a sentence to strike fear into anyone’s heart. The most famous and iconic example of an audit is the dreaded IRS audit. This audit is the IRS’s way of saying, “you did something wrong during the course of an extremely byzantine process we force on you, and now we’re going to make your life miserable by going through every inch of your life with a fine-toothed comb.” Or at least, that is the reputation.

irs

Now, while I’m not here to defend the US tax code nor bureaucracy in general, I will say that this is not exactly what the IRS is saying. Rather, they’re saying, “we’ve noticed inconsistencies between what you’ve reported and what we’ve observed elsewhere, and we are going to investigate further.” And, while this investigation does, in fact, mean a lot of unpleasantness for you, that is not the purpose. An audit, per its dictionary definition, is “a methodical examination and review.”

Audits at Your Place of Business

Considered this way, the word loses some of its onerousness, since it is not deliberately punitive. But it’s still not exactly a cause to throw a party – it means that someone is about to come take a very close look at something you’ve done, with exacting rules and detailed expectations. You’re about to be under a microscope.

Having established that an audit is strict and not punitive, what are the implications for you, as a software developer? What does it mean for you code/software to be audited? If your boss or a colleague utters those three fateful words, “we’re being audited,” what does this mean for your organization and for you?

Well, I’m a consultant, so you can probably predict my answer: “it depends.” “We’re being audited” is informative, but it’s not quite enough information. There are, after all, different kinds of audits, conducted for different purposes. Let’s consider a few of them.

Read More

By

How to Get Developers to Adopt a Coding Standard

Editorial Note: I originally wrote this post for the NDepend blog. Head over to their site and check out the original, here.  While you’re there, have a look around at the other posts; if you enjoy static analysis, you’ll enjoy what’s there.

If you’re a manager, there’s a decent chance that the subject of coding standards makes you want to bang your head against a wall repeatedly.  If you’re a developer, you can probably understand why this is true of your manager, if you think about it.

The group coding standard has the following properties.

  • It’s extremely technical and granular.
  • Developers tend to squabble about it.
  • If it produces any business value, it does so obliquely and theoretically, from management’s perspective.

Thus, if I’m a manager, there’s this inscrutable document out there that causes my team to argue, and whose existence I must take on faith to be a good thing.  As you can see, it doesn’t start out on my good side.

Does It Matter?

There are all manner of opinions and arguments to be found on the internet as to why a coding standard matters (or doesn’t).  I’ve wrote about the subject myself from time to time.  So, without belaboring the point, I’ll make the quick business case for it.

The purpose of a coding standard, at its core, is twofold:

  1. It promotes maintainability by making all code look similar and familiar to all developers.
  2. It standardizes approaches that promote correct code (and avoid incorrect code).

Thus, on the whole, the coding standard makes the total cost of ownership of the codebase decrease by some amount ranging between 0 and “indeterminate.”  As an outside party, you simply have to take on faith that there is an ROI and that the amount of time wasted in arguments, complaining, and compliance is offset by the reduced troubleshooting and onboarding times.

And, in my experience, it generally is.  Notwithstanding pouting and bickering that happens early in the project and makes life unpleasant, it’s better to have these things than not to have them.  The key, then, becomes minimizing the cost of having the standard.  And you do this by securing compliance with the least amount of heartburn for all involved.

So how do you do that?  How do you convince the developers to buy in with a minimum of resistance and friction?

Clipboard

Read More

By

How Code Review Saves You Time

Editorial note: I originally wrote this post for the SmartBear blog.  Check out the original here, at their site.  While you’re there, take a look around at their offering.

Physical labor is one of the most strangely enduring mental models for knowledge work.  Directors and managers of software development the world over reactively employ it when nudged out of their comfort zones, for instance.  “What do you mean ‘pair programming’ — we’ll get half of the work done for the same payout in salary!”  And that’d be a reasonable argument if the value of software were measured in “characters typed per minute.”

WorkHarder

Most of the skepticism of activities like unit testing and code review originates from this same “knowledge work as labor” confusion.  The core value of software resides in the verbatim contents of the source code files, so stuffing all of the features in them ahead of the deadline is critical.  Testing and reviewing are “nice-to-haves”, time and budget permitting.

The classic response from people arguing for these practices is thus one of worth.  It goes something like this: “sure, you can cut those activities, but your quality will dip and there will be more escaped defects.”  In other words, these ‘extra’ activities pay for themselves by making your outfit look less amateurish.  That argument often works, but not always.  Some decision-makers, backs truly to the wall, say “I don’t care about quality — my job depends on shipping on June 19th, and we’re GOING to ship on June 19th, whether it’s a finished product or whether it’s a bag of broken kazoos and cyanide with a bow on it.”

I’d like to take a different tack today and fight a time argument with time arguments.  Instead of “sure, code reviews take extra time but they’re worth it,” I’d like to explore ways that they actually save time.  Whether they save more time than take is going to vary widely by situation, so please don’t mistake my intent; I’m not looking to argue that they’ll save you net time, but rather that they are not exclusively an investment of time.

Read More