Coding to Spec

eading "Dreaming in Code" at the moment. The book portrays programmers as extremely literal and needing to work off detailed specifications.

That has not been my experience at all. When I receive a specification I treat it as a starting point.

• I go through the UI design and alter it to make it more consistent both internally and with any pre-existing parts of the program. User experience is improved by predictability and simplicity.
• I look for common anti-patterns like 20 question syndrome.
• I start asking questions.
• Is the requested functionality already in program? Was it originally in the program but then removed because of negative customer feedback? Is part of the functionality already in the program if so can this be re-used in a natural way?
• If the program is asking the user to make a decision is the information needed to make the decision visible at that point in the program or does the user need flip through several screens to get what they need?
• Is the program asking the user make a decision that they should not be making? It is amazing how often software will throw up a dialog with Yes/No button when it is unrealistic to expect the user to make an informed decision. 
• "Error 1234. Press Okay to continue" 
• "Foo is changing something important. Do you wish to continue Yes/No"
• How easy to undo a decision? People make mistakes. People are also more productive when they can explore different options. Filling the program with "Are you sure Yes/No" messages is not an adequate solution. People become conditioned to hit the "Yes" button automatically without thinking. The brain is every good at filtering out noise.
• Are the terms in the specification ambiguous or have different meanings to different groups?. e.g 
• in the pharmacy industry depending on the context a generic can be either a "set of active ingredients" or a "non-premium brand of drug"
• preferred suppliers are actually manufacturers and not suppliers.
• Does program work with or against the natural workflow of the task?
• Are there non-functional requirements? e.g. security or response time.

After I have gone through some preliminary analysis I will have some hooks to start conversions with the various stakeholders in order to fill in some of  the details missing from the "complete" specification. Taking time to go beyond superficial understanding of the people involved pays great dividends and there are always more stakeholders involved than you first think. After this it is time to start talking to the business about trade offs, options and consequences that they probably have not thought of.

• simplicity, predictability and consistency versus adapting program behavior to context.
• ease of use versus power and flexibility.

I do not always follow this process but when I do I have far better results and when I do not I usually regret it.

If your programmers are complaining about incomplete specifications perhaps you should ask your team some questions.

• Do you have a blame culture? If everyone is busy diverting blame for problems away from themselves no-one is busy finding solutions to those problems.
• Is there to much time pressure? If programmers start asking more questions they are going to get more requirements, which are going to take more time to implement.
• Have you got the right programmers?

I have never seen a complete specification for any project that was not trivial and yet the specification and the project takes life and substance as I communicate with the stakeholders and craft and design code.