Why bother with detailed specs?

Question

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?

Answer 1

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

Answer 2

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.

Answer 3

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).

Answer 4

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.

Answer 5

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.

Answer 6

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.

Answer 7

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.

Answer 8

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.

Answer 9

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.