The Code Whisperer

I’ve seen these phrases many times in business requirements and technical designs:

• when/as appropriate
• when/as necessary
• when/as required

and they always cause trouble.

The phrase “Managing programmers is like herding cats” is a common one and whilst I haven’t tried herding cats, if trying to get my sister-in-laws chickens in the coup is anything to go by the phrase sums up the situation pretty well. Programmers have a mind of their own. They are full of ideas and if you don’t specify exactly what you want, they will fill in the gaps with what they think is appropriate, which is not necessarily what you want. Remember, programmers are very good at finding gaps in logic and filling them, but not always at deciphering wordy specifications.

Let’s look at a situation I came across recently. A change to a PC based system had a business requirements specification, from which a technical design had been written. The writer of the technical design had gone straight on to make and test the changes to the code. There was a lot of pressure to finish the change quickly. The original programmer left the company after the change was completed and a bug was discovered by the test team and assigned to another programmer, who read the technical design and came across the words “write out audit records as required”. As a specific audit record wasn’t being written out a great deal of time was wasted working out what should have been happening from the business requirements, before it became apparent that the problem was a simple error in a complex stored procedure.

There are a number of lessons to be learnt here.

• The business requirements were wordy but not comprehensive. This is often a problem, but it the responsibility of the person completing the technical design to work out which bits are missing and plug them. This should be documented, ideally in the business requirements, but if not in the technical design document. I strongly advocate a design decisions document for a project, which allows the designer to jot down why a decision was made. They may remember it now, but in six months time they may not, and certainly when they leave that knowledge goes with them.
• Technical design needs to be completed by someone other that the programmer. This prevents short cuts being taken in the document (as was the case here) and spreads the knowledge of the change or development. Not all programmers want to do, or are good at, technical design, so it’s important to recognise that and allocate work accordingly.
• Putting too much pressure on time at the design phase can cause errors that are costly to fix later on. We’ll cover this in a later blog, but suffice to say that a good design will be coded and tested quicker and easier than a poor or incomplete design. Interestingly in this case delivery of the software has been delayed due to the number of bugs found in testing. Unfortunately due to staff leaving the code is being corrected by other programmers and is taking longer due partially to poor quality design documents.
• Specification and design documents must be peer reviewed. I’ll be completing a series of blog entries on peer or Fagan reviews, which will detail how to implement this powerful method of improving the software that you produce.
• Ban the phrases listed at the top of this post. By all means refer back to business requirements from the technical design if the business requirements are listed in a fashion that can be understood by the programmer, but if there is any doubt reproduce them so that the circumstances of an event occurring are crystal clear. Understanding a wordy business requirements specification is the job of the technical designer. If the information isn’t succinctly laid out in a table I wouldn’t refer to it.

The message here is straightforward. Spend sufficient time on the design phase, don’t have the same person complete the technical design and the coding and check the quality of the documentation being produced. Mistakes caught here are much cheaper to resolve than if they are discovered whilst coding or testing.