Monday, February 26, 2018

When All Else Fails... Where's the Manual?

How many times have you purchased a product and it required some sort of assembly? You try to put it together only to find you have extra parts left over. As a last resort, you look for the manual. What about when you have to repair it or modify your purchase? Where is the manual?

Concerning software development, if you have a piece of code...a class, a library, or a database table and no one knows who owns it (a.k.a. who created it, is responsible for maintenance, and/or is the source of knowledge for that machine) and something needs to change, either moving to a new system, new feature added, etc, then you have a problem. What typically ensues is similar to what takes place on a factory floor when a piece of equipment that has been running for some time on a production line with out issue needs fixed or new functionality added. 

First, an inquiry is made to the maintenance team asking who is responsible for its upkeep. However, what is found is the maintenance personnel that once created the machine, did the upkeep, and the addition of new functionality is no longer with the company. Then, the maintenance team will review the equipment manual (think dev team documentation here for this analogy). If there is none (which unfortunately is the common case with software that is produced by many dev teams), the team has to consider a few options.

Should they reverse engineer the machine and create a new one? What about simply making the needed changes to the current piece of equipment and risk breaking it? As you know from experience or can imagine, each option has its pros and cons. Yet, wouldn't it be better to have some documentation available to assist? This is why, in my view, documentation is so important when creating software.

Do yourself and others a favor and document with both informative comments in your code as well as external documentation explaining the business rationale as well as a description of your interfaces and objects. 

No comments: