I assume most people have read the Painless Functional Specification articles by Joel. In part two, What's a Spec?, a sample spec is provided. However there is no mention of requirements. I have two questions:
How do requirements fit into the sample functional spec? I assume the requirements must be known before a functional spec can be written. So they can't be part of the functional spec, but where are they recorded?
How does test driven development (TDD) fit into the whole func spec / tech spec split Joel outlines (below):
A functional specification describes how a product will work entirely
from the user's perspective. It doesn't care how the thing is
implemented. It talks about features. It specifies screens, menus,
dialogs, and so on.
A technical specification describes the internal implementation of the
program. It talks about data structures, relational database models,
choice of programming languages and tools, algorithms, etc.
Functional design
This is the WHAT.
What are you designing? What will users do with it? What value will it provide them?
The functional spec is the requirements. Each operation the various users perform (create account, log in, view time) is a requirement of the system.
You have to go deeper, though, and ask yourself, "what happens if Mike can't remember his password?" "What does 'exciting' mean to Cindy?" etc. (This is why Joel notes it isn't a complete spec—it is missing many details.)
TDD
Test driven design is the HOW
How do the classes, methods, etc. work? How are errors handled? How does data flow through the code?
Related
I applied TDD for software development, and it was really good! Now, I'm keen on FPGA design with VHDL and I am wondering about how to apply TDD methodology with it.
Have any of you used TDD on FPGA design? If yes, how do yo do? Do you know any articles or materials to learn about?
Thanks!
I have never specifically applied TDD, but I always have testbenches for the design components in VHDL projects.
Although it is not entirely within the philosophy of TDD, a lot of hardware design end up resembling some of its description. In fact, I would argue that hardware is often much more suitable for testing with fine granularity, because components often have clearly defined inputs and outputs where software units would be depending on many other classes for the functionality to make sense.
The resemblance is strong where all sub-blocks are being properly verified, especially if you consider the blocks to be 'features'. Even more so, when using stimuli files for testbenches on small arithmetic blocks, it is normal to first start with some common and special cases you can think of, and then add more as you find problems in your high-level tests. You will end up working iteratively on a fairly low level.
Some concepts of TDD that don't map well to hardware design include the idea of 'user stories'. Unless if you have specifically designed your project to be extensible, it is more likely you won't see any top level tests passing until all your components are in place.
I don't have any specific links or materials for you. Usually there are many custom scripts involved for running all the tests. Apart from testbenches it often involves checks with assertions, equivalence checks and various forms of formal verification, but doing that in great detail may be more specific to ASIC than FPGA design. The VUnit mentioned in the comment by Briand Drummond looks very interesting.
Note that hardware engineers tend to call checks on VHDL code verification, where testing is what you do on a physical product. I've had one professor that was very passionate about the distinction.
The 'London Style' of TDD suggests focusing on object roles, responsibilities and collaborations, using mock objects to drive out layers of large scale component design in a top down process (as opposed the 'Classic Style' which focuses on algorithmic refinement of methods).
I understand the basic approach, but am wondering how you reconcile this form of TDD (which still emphasises writing a test first) with the more natural way in which we design components, ie. sketching logical designs of related classes and defining their roles and responsibilities on paper / in our heads well before we start writing any code.
Appreciate some real-world advice.
I don't see a need to reconcile TDD (in any form) with "natural" component design. Testing implies that you have an idea of what you test, at the very least you have an interface to some level of precision. Starting out at a coarse-grained component definition seems very "natural" to me.
:)
'London Style' is basically good OOP combined with Outside-in (acceptance test) driven TDD (I am assuming you mean an approach similar to the GOOS book).
That is the way that it "should" be done ; although the "classical" people should have been more explicit about it. I'm not sure there is such a classification among the practitioners (although there are people who are faster with TDD and people who struggle with it).
State-based and interaction-based are styles and are not fits-all-sizes approaches. You need to choose the style for the task at hand.
The problem with doing "TDD in a corner" is that you may end up with well tested code that works but still does the wrong thing from the customers perspective.
Evolution has landed us now into an ATDD cycle which is TDD done at the customer/acceptance level which drives an inner TDD cycle for developers to make the acceptance test pass.
On the "reconcilation":
I've found 'listening to the tests' quite enlightening once you have tuned your ears.. let the tests drive the design.
This is also aligned to the BDD folks. I recommend picking up the RSpec book which has a walkthrough in the first section of the book.
Hi I'm wonderingif someone knows some good resources on writing project specs.
I'm a freelance developer more focused on actual development and less focused
on tech specs.
I'm involved in a proj where have to write technical
specs (& functional req specs) and have absolutely no idea where to
start.. any good site or sample or book you would advise ?
Strongly recommend User Stories Applied by Mike Cohn
Any non-trivial project requires Tech Spec. By non-trivial I mean more than about 1 week of coding or more than 1 programmer.
Although there no much resources online which may help to realize how to make good Tech Specs. So Let me share my vision in this field.
Every spec should contain:
List item
Title
Overview (general words what about the project is)
Operational purpose (what for the project is, the goal)
Functional purpose (the ways and technical methods/resources attained for fulfilling Operational purpose)
Definitions (to avoid polysemy and for clarification purposes)
DATA AND LISTS (the most important and the biggest part of Tech Spec. The section where described data structures, relational database models, choice of programming languages and tools, algorithms, etc)
Wireframes and pages descriptions
Technical requirements (hosting conditions, system requirements, etc)
Сommissioning and acceptance conditions (all criteria which make your job completed)
I was reading Code Complete (2nd Edition), and came across a quote in the margin on page 87 by Bertrand Meyer.
Ask not first what the system does; ask WHAT it does it to!
What exactly is the point Mr. Meyer is trying to get across here. I have some rough ideas, but I would like to make sure I really understand.
... So this is the second fallacy of teleology
- to attribute goal-directed
behavior to things that are not
goal-directed, perhaps without even
thinking of the things as alive and
spirit-inhabited, but only thinking, X
happens in order to Y. "In order to"
is mentalistic language, even though
it doesn't seem to name a blatantly
mental property like "fearful" or
"thinks it can fly". — Eliezer Yudkowsky, artificial intelligence theorist
concerned with self-improving AIs with stable goal systems
Bertrand Meyer's homily suggests that sound reasoning about systems is grounded in knowing what concrete entities are altered by the system; the purpose of the alterations is an emergent property.
I believe the point here is not on what the system does, but on the data it operates on and what those operations are.
This provides two major thinking shifts:
You think of the data and concepts first
You think of operations on that data
With those two "baselines" you will better prepared to organize a system to achieve your goals so that operations on data are well understood and make sense.
In effect, he is laying the ground work to be able to write the "contracts" on the code you write.
From Google search it picked up Art Gittleman's Computing With C# and the .Net Framework:
Bertrand Meyer gives an example of
payroll program, which produces
paychecks from timecards. Management
may later want to extend this program
to produce statistics or tax
information. The payroll function
itself may need to be changed to
produce weekly checks instead of
biweekly checks, for example. The
procedures used to implement the
original payroll program would need to
be changed to make any of these
modifications. Meyer notes that any of
these payroll programs will manipulate
the same sort of data, employee
records, company regulations, and so
forth.
Focusing on the more stable
aspect of such systems, Mayer states a
principle: "Ask not first what the
system does: Ask WHAT it does to!";
and a definition: "Object-oriented
design is the method which leads to
software architectures based on
objects every system or subsystem
manipulates (rather than "the"
function it meant to ensure)."
We today take UML's class diagram and other OOAD approach for granted, but it was something that was "discovered" along the way.
Also see Object-Oriented Design.
My opinion is that the quote is meant as a method to find good abstractions in your software. The text next to this quote deals with finding real-world objects to design your classes.
An simple example would be something like this:
You are making software for a bank. Because your software is working with bank accounts, it should have a class for an account. Then you start thinking what properties accounts have and the interactions you can have with accounts.
Of course, this quote makes more sense if the objects you are trying to model aren't as clear as this case.
Fred Brooks stated it this way:
"Show me your flowcharts and conceal your tables, and I shall continue to be mystified. Show me your tables, and I won't usually need your flowcharts; they'll be obvious."
Domain-Driven design... Understand the problem the software is designed to solve. What "domain" entities, (data abstractions) does the system manipulate ? And what does it do to those domain entities?
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 7 years ago.
Improve this question
So basically I am looking for good templates for writing both technical and functional specs on a project or work request.
What do you use? How deep do you get while writing the specs? Any additional general tips you could provide would be appreciated.
My company needs these badly. I work for a contractor and right now we do not use these documents at all.
EDIT: I have read Joel's take about Painless Specification, I really liked it, but are there any other opinions :)
On general tips;
We are implementing a process of
1) Business Requirements Statement (BRS)
2) Functional Specification
3) Technical specification
The BRS covers what the business problems are, and what the requirements are around solutions, testing, security, reliability and delivery. This defines what would make a successful solution.
The functional spec details what is needed, how it should look, how long fields should be, etc.
The technical spec details where the data comes from, any tricky code that may need to be considered.
The customer owns the requirements. The developers own the tech specs, and the functional spec is a middle ground. Testing is done against the tech specs (usually unit testing) then against the functional specs (usually system testing) and then against the requirements (UAT).
The important part of this (and we are struggling with) is that the developers still need to deliver to the functional spec, and the original business requirements. In reality the functional and tech specs are just there for clarity.
In short, my main tip is to first work out the process you wish to implement. Then seek agreement from all parties involved in your proposed process, then work on the templates to fit. The templates themselves are only are a small part of the change you want to make.
Not a template, but Joel has written a couple of articles on writing a functional spec. He also has sample here.
You can buy templates from ieee and other places, but I have always ended up making my own.
For a technical spec, "Code Complete" by Steve McDonnell has a good checklist, you can draw some info from that. At my last job, I just made a template out of his section headers, and tweaked it from there.
As far as a functional spec, the important thing is to define all the interfaces:
UI (screen mockups)
Software interfaces (plugins, etc.)
Hardware interfaces (if appropriate)
Communications interfaces (Services, email, messaging, etc.)
There should also be a section for business rules, things that are important functionally that are not covered in any interface definition.
If you want to purchase a book, Software Requirements by Karl Wiegers has templates for a few documents as an appendix. Unfortunately, I'm at work and that particular book is at home. If someone has it handy, they might be able to confirm that.
I happen to like this one, among others: ReadySet.
He sells a pro version too.
This is the best one I have found: http://www.jiludwig.com/templates/FRDTemplate.doc
Start off simple, and work your way from there. Since this is your first experience working with this, use a word document with bullet points. Write it, re-read it and provide enough detail that it makes sense. For technical specifications, you may want to lead the developer toward a solution, but for functional specifications the "how" should be completely missing.
I would suggest to have a look at the Roberston's Volere template here. They are part of the Atlantic Systems Guild, together with people like Tom DeMarco and Timothy Lister of "Peopleware" fame.
As the template is copyrighted, I will not reproduce it here, but give you some of the main headers:
The Purpose of the Project
The Stakeholders
Mandated Constraints
Naming Conventions and Terminology
Relevant Facts and Assumptions
The Scope of the Work
Business Data Model and Data Dictionary
The Scope of the Product
Functional Requirements
Look and Feels Requirements
...
There are many more, but this should give you an idea. The most interesting part of the template is the requirements shell that lists functional requirements on a kind of cue card. Again copyrighted, but truly valuable.
Look here in chapter 9.