Write Requirements In Code
Write Requirements In CodeThis page was accidentally replaced with another page's content. Restored to roughly what is correct from history.
Attempted summary of discussion below
Requirements documents often become big, unreadable, ambiguous, unmaintainable messes in the way that other BigDesignUpFront artifacts do. So, some developers believe that instead of creating such a document, it is better to express requirements in code:
The problems with these techniques are that some stakeholders will be unable to interpret code or to directly use the software, so they need an alternative way to determine what the system does or will do so that they can make appropriate decisions. There is also a chicken-and-egg problem: how do you implement a system that demonstrates the requirements if you don't already have a definition of the requirements? Also, this leads to circular arguments about whether the software truly meets its requirements; what the software actually does is not necessarily what the customer wants it to do.
I would agree with only the third point. Unit Tests are a great development tool, but they do not express the operating characteristics of the code. Prototypes do sufficiently express the detailed characteristics of the final software to allow useful evaluation. Give the operational software a test drive as early and as often as possible.
For good or ill, WriteRequirementsInCode is a requirement. A formal requirements specification might phrase it differently ("All requirements shall be written in a computer programming language", perhaps, with additional reference to which languages are acceptable). It is not clear how this requirement itself would be written in code...
The specification of deliverables is part of the contract (external) or development process (internal). In the context of this page, I would assume that delivery of software can be assumed, although there are cases where a contract might call only for a written design. Typically, the decision to use software as the implementation means is made prior to the development of written requirements.
From WaterFall:
The truth of the matter is that it is no more difficult to write a requirement directly in source code than into a requirements document...
Okay, what's up with this? Is it possible to WriteRequirementsInCode? If so, maybe somebody can show me how that's done. If not, maybe somebody can re-state the assertion closer to the real thing. Do you mean "write tests"? Do you mean "implement code that satisfies a requirement so that one may infer from the code what the requirement was"? Just for starters, how do you express "must" or "should" in code? [See Note 1]
Code expresses "is", which trumps all the "musts" and "shoulds" you can write up. In the end, the code will either capture the requirement or not; an intermediate document does not really help.
Um, how does one decide what is until you've explored what are the musts, coulds, shoulds, and do nots? Your process puts the cart before the horse. Somewhere, there must be a discussion of the product and that discussion doesn't produce code. It produces a requirements document readable by presidents, marketing, customers, etc., and it is SignedInBlood?.
Why not produce the software that is runnable and understandable by presidents, marketing, customers, etc? It is actually easier to explore the musts, coulds, shoulds, and do nots with running software than a paper document.
Because we are interested in what should happen. The code, the implementation is totally irrelevant. And many projects require ASICS, hardware, etc., that requirements must be nailed down before they are built. The interaction with software must be nailed down before it is built. Not every project is a single stand-alone program.
In most hardware implementations, the engineers sit down at their CAD systems and start creating schematics. The implementation is highly critical and it is highly important to know what the hardware does before committing to mass builds. Schematics go through numerous iterations of builds and evaluation for timing constraints, power levels, and feasibility. ASICs are often initially developed as PGAs (programmable gate arrays) whose characteristics can be measured well before committing to batch builds. I have rarely seen hardware-software interfaces that were nailed down before they were built; rather, the software takes up the slack for shortcomings in the hardware. Remember, the reason software came into being was to avoid the inflexible nature of hardware; hardware has become more and more programmable to allow decisions to be postponed. Why should we give the software the same straight jacket we are so desperately trying to escape in hardware?
Your team should have been codeveloping hardware and software.
[NOTE: Even co-developed systems require software to accommodate any final slack in hardware. Hardware's physical nature brings the issue of component lead-time into play, so there is a final development window where hardware can no longer change but the software is still flexible. Any deficiencies detected in this window must be corrected in software, or the delivery schedule slipped to allow for hardware changes. The increasing capabilities and affordability of programmable hardware have decreased the length of this window, but it exists nonetheless. As perhaps an example of OldRulesWithOutdatedForces, many systems design groups still just expect to get close with the hardware and clean up the mess with software. ["Amen," said the embedded development congregation.]
The code, the implementation is totally irrelevant.
Anyone care to justify this statement?
mjuchems sez:
I have been running an XP project for about 6 months and have very little paperwork to show for it. We have a bunch of design scribbles on paper and screen prints. You know, everything a programmer needs to code and design. Our customer is happy and the project is way ahead of schedule. However, except for a project charter and small release schedule, we got nothing. (I also have the customer sign off when we are done with some functionality.)
Do you really have "nothing"?? You have a program by now, right? I find the "nothing" assertion implausible, unless the customer has, in effect, signed a blank check. Not even a memorandum concerning work to be done?!
I have been to several XP websites and none mention much about paperwork. I also understand that the lack of garbage paperwork is a big plus in XP.
What kinds of good paperwork are you folks generating?
If you really are doing XP the way the books >hint< it should be done, you can read:
Any further paperwork is entirely within the abilities of the CustomerTeam.
-- PhlIp
After 6 months, why doesn't the customer have some operational software? Even if the customer is not ready for wide deployment, you should probably have at least one prototype site using the software. Let's regard the above section as some code and test it. Here's a good section to test:
[also moved from WaterFall]
Let's regard the above section as some code and test it. Here's a good section to test:
The truth of the matter is that it is no more difficult to write a requirement directly in source code than into a requirements document...
As a setup for this test, could the author above please submit an example or two of a requirement written directly in code, and (optionally) the same requirement written in English prose. I think the first part will be hard enough; hence the second part is optional. -- WaldenMathews
If the requirements are the code then it makes it a little difficult to get started. Our customers might be a little put off as well. Return batch of data in 2msecs would be spread among 100 files. -- AnonymousDonor
No it isn't. If it's important to an OnsiteCustomer it will appear in one place in a CustomerTest. Recall that A> my team wants to document, and B> we intend to write self-documenting code. This is different from not wanting to document, then seeing if the code accidentally does. -- PhlIp
The implementation are little decisions made all over. And there is no one test. It's a zillion different scenarios over which measurements are taken. And I want to trace requirements back to code. A test doesn't do this. It just tests.
See AddingEpicycles
And now, without further ado, an example of a requirement written directly in code...
Okay, what's up with this? Is it possible to WriteRequirementsInCode? If so, maybe somebody can show me how that's done. If not, maybe somebody can re-state the assertion closer to the real thing. Do you mean "write tests"? Do you mean "implement code that satisfies a requirement so that one may infer from the code what the requirement was"? Just for starters, how do you express "must" or "should" in code?
You may have heard of assert statements?
Nobody's saying use only code to document, just use code first.
If a requirement is not eventually written into the code, the requirement is meaningless. Every piece of software is a set of requirements written into code. If you do not expect to eventually record the requirements into the software, why do them at all? We can disagree about the necessity to do a requirements document, but not about the necessity to record requirements into software.
Just an example of a requirement written in the programming language of your choice would suffice. No need to go on about the theory of it. Is the absence of an example trying to tell us something?
Okay: Microsoft Word. Now how about a counter-example of software requirements that are not implemented in the code?
If you seriously think 'Microsoft Word' is an example of a requirement, then we're going to have to go way back before we can go forward. The counter-examples will have to wait. Given the requirement 'Microsoft Word', how is a team or a customer to understand what constitutes a successful implementation, especially if no 'Microsoft Word' has been implemented yet?
If you need the implementation of Microsoft Word in order to evaluate the implementation, you have just validated my original statement. I will restate a very basic assumption - if the requirements are not implemented in the code, the requirements serve no purpose. Pounds of paper stating something does not make the requirement reality; that requires running software.
Maybe you mean "if the requirements never get implemented, they serve no purpose", but even that is too narrow a view. Clearly, if I tell you I need a program to alert me when my bank account balance goes below $100, that statement has value both before and after the software is written.
You've missed my meaning about Microsoft Word being already written. The point is that even if Microsoft Word is written, the utterance 'Microsoft Word' does not convey a usable requirement. And if Microsoft Word has never been written, it conveys even less. Requirements have to be descriptive or they don't work. Perhaps this is why you're not fond of them.
I believe if you talk to people who have used Microsoft Word, the utterance 'Microsoft Word' has a great deal of meaning. People who have used Microsoft Word and never read the documentation for it will have a far better understanding of it than those who have only read the documentation, no matter how theoretical the "quality" of the documentation.
Notes:
1. Words like "should", "may", "as [fast | light | high | etc.] as possible", and all permutations of this drivel, DO NOT belong in a specification. Measurements do. If you want it badly enough, tell us exactly how you want it to perform. PutaNumberOnIt.
The above is one of the reasons requirements documents fail so badly. People work in a fuzzy (as in fuzzy logic) environment. The precise and correct descriptions are terms like the above or like "easy", "fast", etc., with modifiers like "very". Trying to resolve reality into numeric values is difficult, if not impossible. This leads to numeric values which are largely made up and with an unknown relationship to what are the desired operational characteristics. Hence we have software that: meets stated values in excess of what is needed at greater cost, meets stated values that do not provide the desired operation, and numbers that just get ignored. Numeric values are simply not descriptive enough.
How complicated is this bit, really? When I wrote "may", I meant may ... now what the f___ that was doing in a req is something else. The verb I used most was "shall", with an occasional slip into "will". Why would I possibly want to spec using "might", or "perhaps" ... would just as well make do with "on a really nice day if the wind is blowing from the right direction". Stating an objective with exquisite precision is pointless if that's not where you want to go (unless that's the point you were intending to establish?); likewise, all the precision in the world is moot if getting there is nothing but a vague possibility. In my humble opinion, the worst acceptable case is a precise goal being used to measure precisely how we've fallen short. -- BenTremblay
Yes, these are the oft-quoted rules of requirements documents. All requirements use "shall". Expected consequences are described with "will". There are no requirements using "not". So what happens to preferences? Either they get elevated to requirements or left out. How are suggested approaches conveyed? How are possible future directions conveyed? By going to the binary extreme of required or unnecessary, the requirements document loses far too much information.
Oy?!? A requirements document captures information, it doesn't lose it! Look, if you want a certain feature badly enough you'll PutaNumberOnIt and describe it to me in both words and measurements. Otherwise, you don't want it badly enough. There is no Quality Without a Name. Quality can be measured just like any other datum. If you have something you think needs to be a requirement, you have to explain it to me in measurable quanta, otherwise I can't tell if I'm done working on it or not. And believe me, if this is attached to a contract then I will for durn sure insist that you put a number on it.
One point that I think is missed here is that requirement documents aren't for coders. They're for the customer. They are so the customer can go to his boss and get funding for the project. They are there so that the customer doesn't forget a valuable feature that will be needed, but won't be scheduled for the first six months. They exist to make it easier for the customer to pull out features for the next batch of story cards. They are quite frequently the input to the customer from the wider user base the customer represents.
In this environment, putting the requirements into a document is good. Putting fuzzy words like "should" in is good. But giving the requirements document over to the coders and saying "Build this" is a mistake.
Interesting, but this appears to be a highly non-standard definition of a requirements document. This sounds closer to an unsolicited proposal than a requirements document.
I don't see that. What is a requirements document if not a definition of what the solution needs to do?
If it is a "definition of what the solution needs to do," then wouldn't it be intended for the developers? If the document is to "get funding for the project," then it sounds like a proposal to me. It sounds as if the original writer in this section was discussing something other than a common requirements document.
I meant "needs to do from a business perspective". i.e. the client's asking you to write some software. They need it to achieve some business-related outcome. To do that, it has to meet some requirements. The client needs to be able to decide if they're correct (will deliver the business benefit) and the developer needs to be able to decide if they're deliverable. I think this means code isn't the right format for the requirements.
Why wouldn't software be the best meams for determining these issues? Writing the software is certainly the best way to determine the feasibility and running the software is the best way to determine the completeness and usefulness of the software. Doing this exercise on paper is a poor substitute for the real thing.
Because you have to finish the software before you have the requirements, which seems completely backwards to me. Because it's impossible to identify any requirements that have been missed out.
When I write code, it's usually to implement some intent. Requirements describe the intent, so there's a chicken and egg issue. How can I say a list should only have 3 elements without assuming the list into existence? And what if I change the implementation but the requirement stays the same? Should I change the requirements because I changed my implementation?
Writing requirements in code assumes there's a one-to-one mapping between code and requirements. If it doesn't, it will be extremely difficult to understand the requirement. The requirement may involve dozens of cooperating subsystems that may not exist yet. In reality, any moderately complex requirements are based on a great many areas of code. It's not likely many programmers would understand this, let alone customers and managers.
Before implementation, requirements can be expressed as UnitTests.
Unit tests are on what is implemented. Then how can you have unit tests before implementation?
Please show me the unit test for "must have a mean time between failures of > 1000 hours"
In hardware systems, this is done by running multiple systems in parallel under simulated load. Often, the test is run at high temperatures to accelerate failures and derating curves are used to extrapolate operation at normal temperatures. At other times, a system value is determined as a function of the measured failure rates of the individual components.
Yes, but that's not a UnitTest (to me, anyway).
Now, two points. One, if there is no verification of the requirement, then it is not a requirement; it is merely wishful thinking. Two, these types of requirements usually have little relationship to the operational needs of the system, which is "Does the system have characteristics that either hinder operations or cause annoyance?" Reread the requirements stated above and try to determine what it means about the operation of a software program. The statement provides no guidance for either the design or evaluation of the software.
The notion that the software encapsulates the requirements is absurd, in my mind. Consider a physical analogy. Does a used 1999 red Ford pickup truck define the requirements for a vehicle I need? My requirements might have been any subset of the following:
Otherwise, I could assume a requirement for MSWord is that it be difficult to manage very large documents with lots of embedded pictures. <Heh, heh.>
Tests are only slightly better. A set of tests that verifies a particular set of requirement are met will also probably lead one to believe there are other requirements that exist, just because the choice of test implementation exercises a capability that might be there but is not really required.
Are you satisfied with the "used 1999 red Ford pickup truck"? If, so it must meet your requirements. If not, it fails to meet requirements, regardless of whatever list you might have come up with. This is also why most people insist on test driving the specific car they wish to purchase before buying. Look again at the list of requirements provided above and notice how much detail is lost. In the end, the car or the software or whatever else must satisfy its requirements; the only question is whether creating an intermediate written document helps accomplish this.
Can these requirements be written in code?
What makes them not be requirements? As a customer, I want my product created using XP. That means I am making it a requirement. Make a test for it. You can't be serious in saying true requirements can only be expressed in code? That would be convenient.
How would the above list be expressed anywhere outside of the code? How would you possibly identify "once and only once" outside of the source code? How would one refactor, except in the context of the source code? The items listed above are all characteristics of the code, and I don't see how they would be expressed in a textual document as requirements.
Requirements say what the customer wants, not what guidelines the programmers use. I'm not saying requirements can only be expressed in code, or even that they can be. I'm saying those are not requirements.
Your definition of requirement seems to presuppose it can be expressed in code. We get a lot of other types of requirements. Things like you shall make your bug tracking system available to us, you shall be ISO 9000 compliant, you shall be compatible with standards X, Y, and Z, you shall use language X, you shall be compatible with transaction manager X, etc., etc. You want to call them guidelines, but when the customer says to get paid you must do it, that's a requirement any way you slice it.
This sounds like a procurement document, not a software functional requirements document. A department or organization can be ISO 9000 compliant, a planned or existing software program cannot.
I'm not saying requirements can be expressed in code. I'm saying requirements specify what the customer wants. "YAGNI" is not something the customer wants. "YAGNI" is something the programmers want (or not).
As a customer, I wish to specify how software I am paying good money for is developed. For me, it is a requirement. Sorry, we can't do business together.
As a developer, I wish to develop software the best way I see fit. I'm glad we can't do business together.
Clearly you are not in the XP customer decides everything camp.
Nor was I aware XP contained such a camp. I thought XP advocated the customers say what they want and the programmers say how to best provide that.
Customer is king. If they want something and you can't convince them otherwise, then it is so.
I don't think that's specific to XP. That's the free market.
The free market works both ways. As an artisan, I decide if I want to do the work and if the terms are acceptable. The customer isn't always right. In XP, the customer is always right.
So XP isn't subject to free markets? Programmers that practice XP can't quit? Why not?
Certainly they can quit, but if you take a contract and are using XP you let the customer decide. If you think differently, I suggest you read up on XP.
I have. I disagree. If what you say is true, the customer could tell them not to use XP.
Then you get to decide. I suggest then you ask Mr Jeffries. The customer makes these decisions in XP. You don't get to eat your cake too.
Can you cite a reference? I've never seen anything in the XP literature that says the client gets to dictate which guidelines the XP team applies to itself.
As a more practical response, many contract statements of work (SOWs) specify something like CMM level 2, 3, or ISO certification in software development. Almost every contract I have personally worked on also required a documented development process. Like everything else, this process is open to customer negotiation and contracting departments will do that, regardless of what is written in any software development literature.
I don't understand how that is a reply to my question. I've read much of the XP literature, participated in the mailing list, etc., and never seen anything that said clients get to dictate which guidelines the XP team applies to itself.
My point was that the decision to use or not use XP is external to XP. The customer has the right to dictate how he wants a job to be done and to what degree he wishes to give that right up to internal developers or external contractors. As an extreme example, I doubt any XPer would advocate kidnapping cutomer staff if the customer did not choose to provide an OnsiteCustomer. This practice is almost entirely in the hands of the client. This is not unique to XP and the client or upper management has always had the right to require or prohibit certain practices.
I still don't understand how that is a reply to my question.
From TheMythicalManMonth by FredBrooks, January 1982, Pages 64 - 65.
"Not only is a formal definition an implementation, an implementation can serve as a formal definition. ... The manual was vague on some points? 'Ask the machine!' A test program would be devised to determine the behavior ...."
"Using an implementation as a definition has some advantages. All questions can be settled unambiguously by experiment. Debate is never needed, so answers are quick. Answers are always as precise as one wants, and they are always correct, by definition. Opposed to these one has a formidable set of disadvantages. The implementation may over-prescribe even the externals. Invalid syntax always produces some result .... The implementation as a definition overprescribed; it not only said what the machine must do, it also said a great deal about how it had to do it."
"Finally, the use of an implementation as a formal definition is peculiarly susceptible to confusion as to whether the prose description or the formal description [i.e. the implementation - editor note] is in fact the standard."
From ManagingTheSystemLifeCycle?, Second Edition by EdwardYourdon, 1988, Page 9,
"The real impact of the fourth-generation programming languages, in my opinion, is their facility for prototyping, for developing a working software model of the user's new system, instead of the paper model that is discussed in subsequent chapters of this book."
it will not fall out of sync
As refactoring occurs, it will always be out of sync relative to the stakeholders.
How does refactoring make it out of sync relative to the stakeholders? Refactoring should have no effect on externally observable behavior.
Stakeholders are not following code changes, because code usually means nothing to them. If a project is continually refactoring, the requirements will quickly get of sync relative to what they saw at t-1.
Refactoring shouldn't change externally observable behaviour, so they still shouldn't get out of sync. I agree that it's unreasonable to ask the customer to determine if the changed code they see now (after refactoring) expresses the same requirements as the last lot of code they saw.
This is an example of why not to WriteRequirementsInCode. The problem is it's not clear what parts of the code express requirements, and others just express implementation artifacts (many unit tests will be "internal" - testing something that doesn't directly reflect a requirement, but - for example - that a unit conforms to a certain interface that is used by some other unit). So you need to label the "real" requirements, and all of a sudden you're doing more than writing the requirements in code.
If the goal of refactoring is to make the system better, anything can and will change.
But it isn't. Refactoring is improving the code without changing the functionality.
Then you must have been perfect when you created the code in the first place to need no changes. If you were that perfect you wouldn't need to refactor, ever. So, you will end up changing the code in many ways, if you are trying to improve things.
This is OffTopic for this page. Refactoring, by definition, is improving the code without changing functionality. Of course, other changes might be required, but if they change the functionality, they're not refactoring. UnitTests help you check that the changes you made didn't change the functionality. So, no matter how many times you say otherwise, refactoring should not cause the code to get out of sync with the requirements. Other changes might, of course.
You can't RefactoringImprovingTheDesignOfExistingCode without affecting interfaces.
Didn't say you could. Just that the functionality won't change (and so the requirements satisfied, however they're expressed, won't change under refactoring).
As this is one of the reported benefits of refactoring, changes will happen that change the expression of the requirements in code.
I think you're using some other definition of refactoring from mine, so we're just talking past each other. From WhatIsRefactoring:
Silly is saying you can write requirements in code for a system that needs requirements before it ever exists, and then say the code will never change that expresses those requirements.
Indeed. So it's a good thing I didn't say that, then. (I was, rather, referring to the misuse of the word "refactoring".) I'm in the camp that says writing requirements in code is not the right thing to attempt.
EditText of this page
(last edited March 31, 2005)
or FindPage with title or text search