From Joel on Software, 12 Steps to Better Code, Joel asserts that:

Writing specs is like flossing: everybody agrees that it's a good thing, but nobody does it.


Software that wasn't built from a spec usually winds up badly designed and the schedule gets out of control.

I do not agree that specifications work well in software development and that iterative approaches work better.

Is there evidence to support the use of specifications as a way to improve the quality of code?


For clarity, by specification I mean, "a complete description of the behavior of a system to be developed". This is usually the first stage in any Waterfall software development methodology.

  • 4
    Of course "specification" and "iterative approaches" are not polar opposites. I've never read Spolsky as advocating "18-month cycles are where it's at." He just emphasizes more up-front, non-code work than some others. Sep 8 '12 at 17:46
  • 3
    Specifically, are there any advantages to a written spec? In agile we do stories and collaborate face to face on the details... very different from what JS advocates.
    – Sklivvz
    Sep 8 '12 at 20:02
  • 3
    Two more aspects that need to be considered (and I can't see whether they have been in @vartec's answer): (1) Any correlation between use of Agile and smaller, geographically-localised projects that are more likely to succeed anyway. (2) Waterfall is often a strawman. The projects that allegedly use it often have prototypes, alpha/beta releases, and multiple versions and other elements of iterative approaches. Even the original Royce definition wasn't proposing a strict ordering.
    – Oddthinking
    Sep 10 '12 at 8:44
  • 4
    I think this should be moved to programmers.SE. Sep 11 '12 at 16:48
  • 2
    @Chad: That needs references. Iterative development was used widely and successfully for many years before the Agile Manifesto was written in 2001. "Waterfall or nothing" is a strawman.
    – Oddthinking
    Sep 17 '12 at 17:15

First off, when you say "better code" I'm going to assume that you mean that the general software quality of the project is better as opposed to any measure of the aesthetics of the code itself, although code that is easier to read generally results in better quality software.

One of the big area's of study in software engineering research has been to see if there is a correlation between known requirements and defects, these studies shown that adding requirements or changing requirements of a system generally results in more defects. This tends to be bore out by other studies that show a link between changing requirements and schedule and cost overrun.

The core reasoning for most of these finding boils down to knowing what is needed before hand allows for the system to be built to meet those needs and the system can be verified against those needs. This tends to work well in environments well the requirement be explicitly defined, tested, and failure is not an option.

So for at least some segments of software development it can easily be established that specifications result in better code. However, what about environments where the needs can change on a regular basis based upon business needs? In these cases it is important to note that Agile methodologies tend to be used more for internet development than for real-time, control, or systems development. Thus, Agile methodologies tend to target a different development space and we can speculate address different needs. Advocates for Agile development generally call for simple designs and refactoring as a means of ensuring that the code base does not become too complex which has been tied to software defects.

Overall, yes, foreknowledge of fixed requirements results in better code. However, when the requirements cannot be fixed due to changing business requirements, that advantage is largely irrelevant as you may not be able to fix the system requirements long enough to code a major system.


You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .