Monday, February 2, 2009

Avoid the maintenance nightmare of duplications

In software development, duplicate code is considered a sacrilege. It leads to maintenance issues of the system, requiring more work to fix the same problem in a couple of places.

So then, it's pretty easy: just don't duplicate the code, right? It's basically as easy as saying don't eat bad food. Some people have the discipline to stick to healthy nutrients to an extent to which they find junk food disgusting, but the rest of use enjoy a juicy burger once in a while.

Image by Sam UL

As noted by Dave Thomas, one of the two authors of The Pragmatic Programmer:
If you have more than one way to express the same thing, at some point the two or three different representations will most likely fall out of step with each other.
To keep these representations up to date and therefore synchronized with each other, you'll find yourself stuck in the wasteful process of changing them in parallel, which I call the maintenance nightmare. And the nightmare reaches its climax when contradiction makes its way in.

The duplication plague extends beyond code. It reaches areas such as requirements or specifications as well.

It happened to me a couple of times to be directed to obsolete documents, when I started in a new team. These documents usually become obsolete because a colleague sends an email with a few notes, which become new requests upon subsequent replies.

Later on, someone else puts together a Word document that summarizes what has been discussed, which will probably get to be obsolete in a couple of weeks.

A solution that I found working was to establish a procedure of maintaining specifications and, more importantly, to stick to it. This may sound overblown, but it doesn't need to be: a simple guidance, presented as text is usually enough and also newcomers will benefit from it.

When a new email comes in with notes on how a process or a feature must be changed, make sure to update the single location where it was described so far and point everyone to it. Referencing that location in future discussions will habituate your co-workers into using the procedure you established together, eliminating the confusion induced by obsolete docs.


Pawel Brodzinski said...

There's one more issue here. Sometimes PM or a person responsible for maintaining requirements list just don't have a time to update information even when she's aware it should be done.

By the way: "what's not on the list is not in the application" type of approach works quite well. Except management ususally doesn't want to conform to that.

Sorin Ostafiev said...

Pawel, you're right, the "what's not on the list is not in the application" is a good way of forcing the requirements update. :)

The requirements/specifications approval has to be, as you indicate, the responsibility of the PM. But everyone in the team should be encouraged to write a short description of a process or feature, if this doesn't exist, and then ask for the PM to approve it, rather than rely on her/him to keep the list up to date.

And, as the post stresses on, to keep it in one place only. :)

Thanks for the comment.