Does having a specification result in better code?

Question

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.

And:

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.

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, Sep 08 '12 at 17:17
I would say that he made a generalisation; he said everyone agrees and I disagree. I'm looking for evidence that contradicts his assertions. — Dave Hillier, Sep 08 '12 at 17:30
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. — Larry OBrien, Sep 08 '12 at 17:46
Here's a relevant quote from Spolsky re specs and iterative approaches (http://www.joelonsoftware.com/articles/fog0000000035.html): "Some programming teams adopt a "waterfall" mentality...This approach is why specs have such a bad reputation....My specs are updated frequently. The updating continues as the product is developed and new decisions are made." — Larry OBrien, Sep 08 '12 at 18:26
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 08 '12 at 20:02
On the other hand: define "better" code, or "better designed" or even "schedule" or "out of control"... — Sklivvz, Sep 08 '12 at 20:03
Given that most waterfall projects run over time and over budget, and result in overall failure, it's really hard to agree with the second quote. — vartec, Sep 10 '12 at 08:16
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](http://en.wikipedia.org/wiki/Waterfall_model) wasn't proposing a strict ordering. — Oddthinking, Sep 10 '12 at 08:44
@Oddthinking: regarding strict ordering, the Wiki page you link to reads *"waterfall model maintains that one should move to a phase only when its preceding phase is completed and perfected"* — vartec, Sep 10 '12 at 09:03
@Sklivvz - I agree that "better code" needs to be better defined; however, the generally understood meaning in the software community is that there is a low rate of defects in the application. — rjzii, Sep 10 '12 at 12:51
@vartec: You are right and I haven't explained myself well. Sorry. My key concern is that I often see a false dichotomy being offered (not in your answer!) between waterfall and agile. Most of my s/w career has NOT been using Agile methods. NEVER in my career have I used the caricatured pure waterfall model or seen it being used. (I don't oppose Agile; I oppose it being oversold.) — Oddthinking, Sep 10 '12 at 15:06
@rob that's an invalid representation of the problem: waterfall development tries to get as fast as possible to a known solution; agile tries to get as close as possible to a partially known solution within a fixed time. Neither claim a lower defect rate. — Sklivvz, Sep 10 '12 at 17:33
@Sklivvz - That's the first time I've ever seen "waterfall development" (waterfall model) in the same sentence as "fast as possible". — rjzii, Sep 10 '12 at 18:37
I think I might be able to pull together a reasonable answer to this, but can you define what you mean by "specifications" first so we can have an agreed upon base line? Given that specs can run the gauntlet from a couple hundred pages of useless text to a couple pages that spell out the critical features I want to know which direction to try and research towards. Although I suspect the answer will be "There is no silver bullet, it depends on what you are writing." — rjzii, Sep 11 '12 at 22:37
http://en.wikipedia.org/wiki/Software_Requirements_Specification the first block on any waterfall diagram — Dave Hillier, Sep 12 '12 at 19:09
@DaveHillier its probably a dupe on programmers, http://programmers.stackexchange.com/search?q=agile+vs+waterfall — Ryathal, Sep 12 '12 at 19:30
@Ryathal that's not very helpful - you could have just provided a link to google with the same search — Dave Hillier, Sep 12 '12 at 19:53
@vartec - I would suggest that they run over because the spec was changed, scope increased, and timeline condensed from what was presented originally... at least that has been my experience. Which is why most of us that actually care about the quality of the end product prefer agile. — Chad, Sep 17 '12 at 15:50
That blog was written ~6 months before the Agile Manifesto was released. At the time waterfall was the best way we had to manage software development. So it was really waterfall or nothing. You can not really compare agile against this post since the post predates agile. — Chad, Sep 17 '12 at 15:54
@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
@Oddthinking - The blog referenced was written August 2000 about 6 months before the Agile Manifesto was written in Febuary 2001(12 SD Times March 2011) There may have been iterative approaches used but nothing really formalized with a standardized way of documenting. And it was not wide spread. If you want to talk to the masses you talk about what they are using not about niche markets. — Chad, Sep 17 '12 at 19:11
@Chad: From Wikipedia: The first formal description of the waterfall model is often cited as a 1970 article by Winston W. Royce, although Royce did not use the term "waterfall" in this article. Royce presented this model as an example of a flawed, non-working model. — Dave Hillier, Sep 17 '12 at 19:24
@DaveHillier - Do not get me wrong... I am not a proponent of Waterfall. But the question context gets blurred when you realize that it was written at a time when waterfall was the only widely adopted methodology out there. — Chad, Sep 17 '12 at 19:28
@Chad, I disagree with the assertion that waterfall was the only adopted methodology. I was taught about waterfall as a flawed model in 1995. The Boehm Spiral Model was suggested instead. — Dave Hillier, Sep 17 '12 at 22:01
Steve Connel, [Rapid Development](http://my.safaribooksonline.com/book/software-engineering-and-development/9780735634725), 1996: Chapter 7 describes several different non-waterfall models. Fred Brooks, The Mythical Man-Month, 1975: Describes prototyping. I was coding iteratively, with many different project lifecycles, for many years before Agile. — Oddthinking, Sep 18 '12 at 01:13
@DaveHillier - Name 3 major businesses that adopted that model... that the models existed is irrelevant if business is not using it. — Chad, Sep 18 '12 at 14:18

score 10 · Answer 1 · edited Apr 20 '22 at 11:27

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.

Luxspes · Accepted Answer · 2022-05-09T13:21:45.807

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.

Does having a specification result in better code?

2 Answers2

Linked