Friday, October 16

Coding to Spec

Reading "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 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.

2 comments:

O.K. said...

In my observations, a lot of SD process management books like to portray software developers like some sort of kindergarten kids who require paternalistic guidance by management/"business"/marketing/etc... (and who like to "code" just for the sake of it, as in – rather meaninglessly, and, curiously, it is perceived that they don't need much in reward - just let them code ;)...

All of this is "B.S.", IMHO and I guess its purpose is primarily to justify the function/role/existence of the latter... (and often higher salaries ;)

In the real world however, I just as you probably, have seen great many cases when logical and so called "business level" flaws were skipped unnoticed by "business analysts", "subject matter" experts” and etc and were only picked up and pointed out by some lowest ranking (non-senior) "developer"... when it came to actually implementing it in a software system...

And I have come up with a very simple explanation for it: folks who study (or are self-tout) in engineering, maths, CompSci or just programming per se are both inclined to naturally and also used to by their daily job to think LOGICALLY (is it what the others label as "literal"?) and actually do analyze things for consistency, cause/effect consequences etc... whereas folks who study or do purely some "soft skill" or "managerial" disciplines they are inclined to deal with things at a level of some “comfortable vagueness” (mind you, not _abstraction_ - but actually vagueness) at which everything looks ok! and rosy and no issues are visible...

Tara said...

Interesting look into the mind of a programmer - as a recruiter who doesn't have a technical background this is very educational! Thanks! Tara