When writing software, what's the point of writing a formal, detailed dead-tree specification? To clarify, a somewhat informal, high-level specification for people who don't want to read the code makes sense to me. A reference implementation in well-commented, readable source code is about the most unambiguous specification of anything you're going to get, though, since a computer has to be able to execute it. Formal specs are often just as hard to read, and almost as hard to write, as code.

What benefits does a formal specification offer over a reference implementation plus a little documentation about what behavior is undefined/implementation-defined regardless of how it works in the reference implementation.

Edit: Alternatively, what's wrong with the tests being the formal specification?

  • 7
    Why does it have to be "dead-tree"? Why not a wiki or PDF? Mar 23, 2011 at 19:20
  • @Philip: No reason in principle. It's just that very formal documents tend to get written on dead trees, especially at big, bureaucratic organizations like the ones I'm picturing.
    – dsimcha
    Mar 23, 2011 at 19:22
  • Software specs are great for programmers to use for themselves, but even better to use for customers such that they define their expectations of the end product concretely... before you start working your magic.
    – ToTheBeach
    Mar 23, 2011 at 19:58
  • 2
    I'm in favor of high level specifications. Just enough detail so that the client understands what they are getting and the developers understand what the client wants. Any more detail than this and you are going to end up maintaining documents instead of code. Mar 24, 2011 at 14:28
  • @Berin: Right, this is what I meant by an informal, high level specification. When I wrote this question, I was thinking more about standards (for example, C++ compilers) than business software.
    – dsimcha
    Mar 24, 2011 at 17:19

9 Answers 9


How can you know you're done, if you don't know what it's supposed to look like when it's done?

Feature creep will catch you. You'll be trying to deliver for a client, and, as completion time rolls around, they're going to discover 10,000 little things that they absolutely have to have.

In order to get paid, in order to get your boss off your back when the deadline goes sailing past, you need to be able to pull out the spec and say, "All my time and cost estimates were for this thing, not this new thing that everyone has decided they want."

  • 13
    My only regret is that I have but one upvote to give for this wisdom.
    – Dan Ray
    Mar 23, 2011 at 20:14
  • 3
    +1. Wisdom. That said, the last shop I worked at was a subscription based business model where the clients keep paying for the existing licenses while screaming about other features that they just have to have (eg. You risk eventually losing them if you don't implement their scope creep - but they're paying you at the same time so you want to make them happy). But typically, you're not being paid while implementing scope creep. Also: that business model can really make the developers feel like dead end codemonkeys. Mar 23, 2011 at 21:28
  • 1
    +1 I came to programming via engineering HVAC control systems - a typical specification for a building would be several hundred pages. Projects were accepted by the consultant/client when all points were ticked - variations would incur a cost and extended deadline. The thing is - for some reason, it seems to be in general software development that the specification should be written by the implementor - I think this is wrong - in HVAC, the specification came through a building consultant (although the implementor could query and challenge the spec at any time).
    – HorusKol
    Mar 23, 2011 at 22:14
  • 1
    "as completion time rolls around, they're going to discover 10,000 little things that they absolutely have to have" But that's only true for custom-made software. If you develop a shrink-wrapped software or an in-house software, it's done when you say it's done. There will always be requests for additional features. Some of them will be included in a future release, some won't. I don't see the benefit of detailed specs here.
    – nikie
    Mar 24, 2011 at 14:39
  • 2
    @nikie: Tell it to the Duke Nukem design team. You have to deal with QA, marketing, phbs who read too many magazines...It still matters. Mar 24, 2011 at 14:46

Specifications allow you to ponder over things without having written a lot of code up front which would have to be changed, if the specification changes. Consider it to be between blackboard and actual coding

It is also a very good idea to do when having several independent parties writing components needing to go together.


In addition to some of the other very good reasons mentioned already, having a formal spec allows you to CYA - Cover Your Ass! If the managers/analysts/testers say you didn't build something correctly, you can point to the spec and say "I built it just as you wanted it!". This includes low-level stuff such as "All data persisted to the AXX_RGV table must be in UPPERCASE", "Web forms with less than 3 input fields should have the Submit button on the lower-left", etc...

Also for when people forget things on a very long and large project, having a detailed spec to refer to can be very useful. Just remember that the spec should be a Living Document, and if the requirements change (through what is hopefully a documented and formal process), so must the spec. Yes, this can take more time. In my experience, it's worth it (if it's done right).

  • 1
    +1 for maintaining specs through the life of the project. Mar 24, 2011 at 20:31

A formal specification of the requirements of a program in needed because the software engineer needs to know what to implement; the QA engineer needs to know what to test, and the customer needs to know what to expect.

Having a spec allows you to know when you are done programming.

  • 1
    I believe that the OP was asking about the usefulness of detail design specs. Everyone knows that a well-written requirements document is critical to the success of a project. I am not so sure that detail design specs are as useful today as they were when we were using much lower-level programming languages. Back then, a detail design spec laid out in pseudocode what needed to be coded. The implemented coded was checked against the psuedocode during a code review to ensure correctness. This orientation also had a the side-effect of producing an underclass of coders who coded from spec. Mar 24, 2011 at 16:49

One of the primary benefits may be safety. I wouldn't want to fly in an airliner where the specification of the control systems was a reference implementation. I really want someone to specify what the systems need to do in a form someone who is not intimately familiar with the software can understand. I would expect each requirement has been fully verified by testing.

For less safety critical systems, specifications are communication tools. They should detail what the system needs to do in sufficient detail to construct and test the system. How the system does this is the responsibility of the code. The detail required will vary depending on the domain expertise of the development team and access to domain experts.

Specifications should always match the implemented systems. If errors are found in the specification, the specification should be updated.

Error causes estimates I have seen indicate test failures are relatively evenly split between errors in specifications, code, and tests.


Working on a large project right now. So far the spec has helped QA identify what to test, has allowed us to charge the customer more (significantly as in millions) when in User testing, they decided that what they had agreed to wasn't what they really wanted, enabled the people doing code review to see if the code met the requirement, allowed the devs to have a basis to check to see if they were finished and to point to the spec to settle disputes as to what the module should contain. It also allowd us to identify devs who weren't producing what the client required before the client saw the product and that ended up as a basis for getting rid of some people who cosistently could not follow the spec. The complexity of our spec helped the client realize that we weren't being outrageous in our cost and time estimates. A good spec is worth it's weight in gold (So glad we have the world's best business analyst).

I wanted to add, I have worked on projects with good specs, with bad specs and with no specs. The ones which ended up being the worst were the no spec ones because the development team and the client always had a different internal vision of the end result. These are the projects where you go around muttering, "where can I get a mind-reading module?" Guessing what the customer might want is a horrible experience. Bad specs are not not much better, but at least you can refine as you go and say, "I'm not sure what you meant here." in order to get more information before wasting your time building the wrong thing. The big project I'm on right now has amazingly good specs, it's made life easier and much less stressful.

  • +1 - Sometimes you have to realize this is a business involving technical and non-technical people see the big picture in many ways.
    – JeffO
    Mar 23, 2011 at 22:26

I think this question is the crux of the agile vs. waterfall lifecycle question.

If you're doing agile, a basic premise is that the code coupled with close developer interaction is better and faster than the detailed specification. The team prioritizes releasing new features and high quality over other things - like formal communication mechanisms such as detailed design specs. But there's a trade here - you have to have communication channels between team members that let them ask about nuances and detailed design intention when they need it.

If you're doing waterfall, you're working under the assumption that the work of filling in the code under the detailed design and then testing it is significant. And you want to give stakeholders early insight into how this work will proceed and what it will be like when it's done. That may be vetting the design with the customer to make sure you've scoped out features that make sense. It may also be to vet it with experts in other arenas - such as safety reviews, security reviews, and reviews by team members that have to integrate with your code. The assumption is that these reviews will save time in the long run because they will save you from investigating a large amount of time in developing the wrong thing.

Lately, I've seen some really great fusion between detailed designs and code comment tools - JavaDoc for example. Since most detailed designs are foot prints of the code and short explanations of what it will do - this is more or less the same thing you'd expect as code comments. So having a tool that will transform code comments into a detailed design spec is great - a much better way to keep it up to date than doing it by hand.

I believe that inaccurate assessment of how detailed design should be for the project, is a major factor in cost growth. The worst part is that you're damned if you do and damned if you don't:

  • If your design is too detailed for the size of the team, the complexity of the work, and the requirements of the gates you must get through (security reviews, safety reviews, etc.), then you've wasted precious time and money on an artifact you will never use.
  • If your design is not detailed enough, you will waste money as team members make incorrect assumptions that lead to integration issues, and you risk heavy rework when a final security or safety audit uncovers issues that could have been fixed early and cheaply if they had been clear aspects of the design prior to implementation.

I don't feel it's a black and white case - there can be plenty of times where some components are "good enough" if designed at a high level, while others need rigorous detailed work. And changing team or project environments can dictate new design needs as a project evolves.


Personally, I think detailed specs overrated.

In my experience, what the customers need and what the customers think they need are often two different things. If you freeze requirements early on, you're building what they think they need, not what they actually need. Legally, you're on the safe side and you'll get paid, but you won't have a happy customer.

On the other hand, if you accept that software development is to some extent an exploratory activity, you'll try to keep requirements open for as long as possible. Discuss with the users what you need to know for the current iteration, no more, no less. And know that sometimes, you'll have to revisit these decisions in a later iteration. Most importantly: Keep in mind that if that happens, it's not the client's fault. Unless your users are software developers, too, requirements gathering is not part of their job description. It's part of your job description.

So how do you prevent feature creep? Ideally, by having a sane product manager who is in charge of accepting or rejecting feature requests, and who can not be overruled by anyone else.


Agile is 10+ years old, so this isn't a new phenomenon.

I would hope the specs would be a lot shorter than the code, so I don't know how much detail you need. There should be enough to keep team members in the loop. Is reading all of each other's code practical/necessary?

Agreed, no need for dead documents. I'd rather approach an unfamiliar code base with no documentation than incorrect documentation.

And if the computer is so good at executing your code, why don't you let it make it's own changes? Following the recipe on the back of the box doesn't make you a chef.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.