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.

  • 1
    Surely this is just a proof by disproof, i.e. if I can find one example of a project with a specification that worked well then there is evidence. What is the standard of evidence required to prove it?
    – Ben
    Commented Sep 8, 2012 at 17:17
  • 7
    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. Commented Sep 8, 2012 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
    Commented Sep 8, 2012 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
    Commented Sep 10, 2012 at 8:44
  • 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
    Commented Sep 17, 2012 at 17:15

2 Answers 2


After reading this question I wondered if there be statement about this on the free book Evidence-based Software Engineering.

After a quick review I was able to find a statement on chapter 6 "Reliability", section 6.4.1 "Where is the mistake?/Requirements" that seems relevant to the question of "Does having a specification result in better code?" :

There have been very few studies of the impact of the form of specification on its implementation

The 1 study linked from that statement : "The Effects of the Symbology and Spatial Arrangement of Software Documentation in a Modification Task" is from 1981

The study describes a series of experiments to evaluate the effects of the format of software documentation on programmer performance and finds that: "the more succinct the [specification] symbology, the better the performance." with performance being: "the number of errors which appeared in the first submission of the modified program". Time of implementation was also considered but in that regard succint specification symbology seemed to have no effect.

One can also find some tangentially related studies on Chapter 7 "Source code" section 7.2.3 "Desirable Characteristics/Explaining Code" showing evidence that high level models aid general human mental comprehension.

In summary I think this shows the way the specification is written, has an effect on the amount of errors the resulting code has. I believe this answer the question because, if one thinks about this carefully, having a specification is unavoidable. One can only have different forms of specification, total lack of specification of any kind would mean total lack of any goal for the coding effort, which would render any effort to measure how good the code is impossible, since there would be no goal to compare against.


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 areas of study in software engineering research has been to see if there is a correlation between known requirements and defects. These studies show that adding requirements or changing requirements of a system generally results in more defects. This tends to be born out by other studies that show a link between changing requirements and schedule and cost overrun.

The core reasoning for most of these findings boils down to knowing what is needed beforehand allows 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 where the requirements can be explicitly defined and 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.

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, but 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 .