What Isa Specification Anyway
What Isa Specification Anyway
A specification is just a detailed description of something to be built, but that's a rather loose definition, and one that can be improved if we are willing to investigate what it means to be a good or effective specification.
A specification is an explicit, and preferably concise, design result that is complete in scope and adequately detailed.
Specifications are explicit by definition. They differ in this from requirements, which may be implicit or unstated (and hence overlooked), and can therefore be said to exist, in some sense, independently from their expression (see BusinessRequirements).
Whether a specification is concise does not, of itself, affect its status as a specification. The concise is preferred to the verbose because it tends to be clearer and more digestible. Clarifications (definitions, exceptions) themselves form part of the specification but it is often useful to present them immediately after a more terse presentation that excludes them (an example of the PyramidPrinciple? see ThingsInThrees). Commentary and examples, on the other hand, whilst often useful as an aid to understanding, do not form part of the specification; they can be said to be ‘wrong’ if they are at odds with the specification. (In the real world, the example is quite likely to be right and the specification wrong, but formally, the specification is axiomatic: never ‘wrong’, only ‘incomplete’, ‘inconsistent’, ‘incoherent’, ‘inconvenient’, ‘incomprehensible’ see ZeroDefects)
A specification is a design result. The process of specification may therefore overlap with the process of design, and it usually does. But design is fundamentally a matter of making choices, whereas specification is the act of recording the choices made (and the resultant record is a specification). Thus you can have design without specification but not specification without design. If you move directly from making the choice to writing code that reflects that choice, as described in ClarityUpFront, then TheSourceCodeIsTheSpecification.
A specification should explicitly state what it is a specification for. Even if it does not, it must have an implicit scope. In either case, the specification must "deliver the goods" and be complete in scope. A specification that addresses some of its scope but not all of it is technically defective: a partial specification. In everyday usage, the specification is usually (invariably?) only a partial specification, because it is often (considered) unnecessary to make every last thing explicit. (If the explicit scope of a specification makes clear exactly what is not being specified, however, it thereby becomes complete!)
Enough is enough. Too much is also enough. Adequately detailed means that all the detail necessary for a specification’s purpose is present. Superfluous detail should be avoided in the interests of keeping the specification concise. It may be desirable, however, to create a single specification for multiple purposes, particularly if the resultant specification is still fairly short. In this case, the detail must be adequate for each and every purpose and is therefore likely to be excessive for some purposes.
Discussion:
In light of the above, what can be said about TheSourceCodeIsTheSpecification, TheUnitTestIsTheSpecification or TestsAreAnExecutableSpecification ?
TheSourceCodeIsTheSpecification's stance is that TheSourceCodeIsTheDesign distances non-programmers from the design process. But does TheSourceCodeIsTheSpecification allow non-programmers a say in the specification process? I think not.
Uh...I don't think marketing (for example) cares about the low-level specification (implementation) of a product, they are much more interested in the high-level design and that this design is satisfied.
Things to do (urgent): ask a non-programmer whether they'd prefer to specify a program, or design one.
Just guessing, but the likely response from programmers and non-programmers alike will probably be "What do you mean?". You'll have to define your terms.
Suggested definition:
A specification for a requirement is a detailed description of inputs and their corresponding outputs needed to meet the requirement. That is, for input A, the process should generate output A1, for input B, output B1, etc. Note that the output can also be an error return.
With this definition, I would suggest that an AcceptanceTest is closer to a specification than either the source code or a UnitTest.
-- WayneMack
They are all specifications, their scope and purpose are different though. To get close to an adequate system specification you probably need all three.
The only thing that fully specifies a system is the system itself. The phrase "fully specify" is something to watch out for. An "adequate specification" of the system is more often of value. That's a discrepancy of interest to engineers, not mathematicians.
Although I am opposed to using the phrase "the specification", I think when used, it implies the system specification, not a module specification, so Wayne's point about AcceptanceTest holds. But until you define what test means, I'm not convinced that a test can be a specification.
This is confusing, because most things in software are specifications of one kind or another, including specifications of specifications. This nestedness of specifications is one of the things that make software hard.
Here's my take on a what a spec is for:
The three main purposes of a specification document are that it:
- demonstrates that requirements can be met,
- clearly states any issues or difficulties,
- interprets requirements into instructions for a programmer.
If these objectives can be met, on paper, before coding starts, most of the parties involved can have more confidence that the project may succeed.
Of course, this is made easier if the requirements are already written down, in broad terms and short statements from the users perspective.
However, I think you can meet these objectives without a specification. I see a specification as much more like a blueprint. It contains detailed schemas, detailed flow-charts, state-diagrams, and so on. It is VERY close to the code, whereas a role-diagram or even a basic class diagram is more abstract. With today's high-level languages, I don't feel these close to the code specifications provide any additional value. It should be clear that I am not talking about the specification of the application (a.k.a. the requirements) but about the specification of the source code - what used to be called the detailed spec. I don't think this tosses out other detailed descriptions, such as the five viewpoints of RM-ODP. The idea is to reduce redundant work without removing value. These days, detailed specifications rarely stay current and rarely add value, while often taking as much time as the actual coding. -- RobertDiFalco
The main value I see for "close to the code" specifications is in circumstances when the code does not yet exist. Recent experience has shown that the producing such a document was crucial to the success of an urgent small project. In this case, the programmer and the management both agreed that quick success just would not have happened without producing a specification. Throwing the requirements straight at the programmer would have been a disaster.
Regarding charts and diagrams in specifications, I am of the opinion that they should never be a substitute for clear and concise text. Sure, you can "get the picture" more quickly with a nice chart or diagram (or ten!), but the essential ideas should always be expressed in plain text -- RichardCollins
There's a tendency to think domains and requirements are abstract, while only code is really detailed. It's a fallacy, of course, and one that MichaelJackson has done well to debunk in his book on requirements and specifications. I find descriptions of code to be too much like code to be useful, which is Roberts point. However, detailed descriptions of domain characteristics are extremely helpful, as well as detailed descriptions of how the system will interact with the domain. (These are properly termed specifications, but are they the specification?) These detail decisions are often deferred to coding under the fallacy above that details should be handled last. That's where a lot of trouble starts.
The "anyway" tacked onto what ought to be the title of this page is a highly significant detail that implies that we bat words about without knowing what we mean or what they mean or what others think they mean. We gotta cut that out.
True - we have gotta cut that out. Originally, it was a take on WhatAreComponentsAnyway. -- MattRickard
There's a tendency to think "abstract" and "detailed" are antonyms. It's a fallacy, of course.
I would like to expand briefly expand upon RichardCollins and WaldenMathews.
The four main purposes of a specification document are that it:
- demonstrates that requirements can be met,
- clearly states any issues or difficulties,
- interprets requirements into instructions for a developer,
- details shared resources that many developers will might need to collaborate - schemas, sequence diagrams, interfaces, physical resources.
-- TimTwelves
EditText of this page
(last edited September 16, 2005)
or FindPage with title or text search