DANSE design document template
From DANSE
About the DANSE design document
What is the DANSE design document template?
- It is a document that provides a series of questions that a DANSE developer should answer in the design phase of the code. The answers to these questions are intended to be a living document that will grow, over the course of the code developement, into the specification and developer's manual for the code. The answers to these questions should be the critical documentation that a new user, or especially a new developer, will read to get a robust understanding of the functions performrd by the code and how it works. The complete set of requirements identified in the template will grow into a logically consistent behavior specification. Additionally, the set of components (or functions) identified in the template should span all the code planned for implementation and ultimately be captured in the architecture specification.
How can I get a copy of the DANSE design template?
- Copy and paste the following into a text docuement.
* Application: WBS-X.0.X APPLICATION_NAME * Statement of purpose, functionality, and acceptance criteria: ... * Summary of basic methodology and procedures: ... * Description of components and functions to be added or modified: ... * Critical use cases and behavior tests: ... * Criteria for validation of results: ... * Requirements and constraints: ... * Additional notes: ...
Do I need to have complete answers before I start prototyping?
- Arriving at a consistent and complete specification and a viable architecture may require prototyping to establish feasibility or to clarify requirements. Prototyping should be recognized as part of the specification process. The objectives of any prototyping activity must be clearly defined. The more upfront design documentation that you produce before you write any code, will help you better structure the code and develop it more quickly. However, inevitably there will be times that protopyping of the code is critical to the rest of the design of the code. My suggestion is to make a quick write-up of the initial plan, and then turn to the prototyping to try out your plan. Then once the design of prototype has been sufficiently tested, return to the design documentation and modify it accordingly. The bottom line is: do the design document first to explain your thinking, then modify it as needed -- it is highly unlikely that the initial design of any code will end up as the final design. If you have a clear idea of the structure and behavior of your code, then you will have no trouble giving lengthy details to all of the above bullets. If you have difficulty answering one or more of the bullets, that means that more design activities (thinking, documentation, and prototyping) need to be completed before you actually start to implement your code.
What design activities should be completed before actual software implementation can begin?
- A complete and consistent behavior specification must exist, and the application-level architecture must be defined. The behavior specification is based on functional requirements; while the architecture may depend on a number of factors related to developer productivity, maintainability, reusability, and testability. Once an initial behavior specification and architecture are defined, changes identified during code implementation are tracked via the project's configuration management process. This means that the code structure has been specified with enough completeness that architecture descriptions can be generated by automated tools such as doxygen and that prototyping has successfully validated critical functional requirements and demonstrated feasibility of the implementation strategy.
What do all of these bullets mean? Which are the most important?
- A detailed explanation of each bullet is found below. They are all important, in that they provide a seamless path from informal requirements to complete and consistent specifications.
What do I do with the DANSE design template?
- It should be committed to the DANSE repository in the same directory as the package being developed. The current suggestion is to create a directory called "doc" where the design documentation will live (doc will be the location of the manual). So for a package "foo", along with the standard "foo/foo", "foo/libfoo", "foo/tests", and so on, you will now have "foo/doc".
Detailed explaination of each bullet
Application: WBS-X.0.X APPLICATION_NAME
This is a statement of the name of the application or component, and the corresponding WBS number.
Statement of purpose, functionality, and acceptance criteria:
Statement of purpose is the general description of what your vision is for the software. It states what you plan to accomplish, and why.
Functionality is a top-level description of what your code should be able to do. For example, if you were describing a graphics package, some of the functionality may be:
- must be able to take N-column ascii data and produce a line plot, contour plot, or surface plot
- must be able to save generated plots to picture file, and modified data to ascii file
- must be able to zoom and pan current graph; must be able to produce paper-quality output.
Acceptance criteria are the target for what you will accept as a finished product. This means once you reach your acceptance criteria, you can stop development. For example, again describing the graphics package, acceptance criteria may be:
- can produce a line plot, contour plot, and surface plot from N-column ascii data
- can save generated plots in .jpg format, and modified data as N-column ascii (where "modified" means rotations, subsets, and supersets)
- can zoom and pan from commandline (mouse-click is optional)
- can render 1MB data without severe (1 sec) lag.
Summary of basic methodology and procedures:
The basic methodology and procedure is a descriptive summary of how your code will work. It is an explanation of how your code will accomplish it's intended purpose. This explanation should be approximately how you would describe the completed product to a new graduate student or a new developer. A UML or flow diagram for this application (or component) is an appropriate level of description, however generating such a diagram is not required. In the case of relatively complex applications or components, a preferred method of referencing and linking multiple code pieces should be described.
Description of components and functions to be added or modified:
This is a further description of the modular units that compose the application (or component). Here, the inputs and outputs for each of the components and functions should be stated. Also, a description of the algorithm (or code block) that will be used in each component core or function core should be specified. Any third party software (i.e. "use Matlab's gradient search") or named technique (i.e. "use a FFT to transform x to inverse space") should be mentioned here as well. The explanation should be detailed enough to give an understanding of the content of the code without having to read the code. All code utilized in the building of the application or component should be accompanied by a corresponding description, with the exception of third-party code or other packages that are treated as a "black-box" -- however, any modifications to third-party code or other packages should be documented in the same manner as new code.
For example, for an 'add' function, a description may be:
INTERFACE:
METHODS:
sum = add(x,y) --> given two numbers return their sum
INPUT:
x is a double, is required for add, and is defined as the augend
y is a double, is required for add, and is defined as the addend
OUTPUT:
sum is a double, and is defined as the sum (i.e. x plus y)
IMPLEMENTATION:
DESCRIPTION:
will perform simple addition of x and y
to be written in python as a function (i.e. not a class)
ERRORS:
add throws error when x or y are not doubles
add throws error when x or y are not given
Critical use cases and behavior tests:
Critical use cases refer to a description of specific ways that the code will be used. These should be examples of how the code will commonly be used, and are important to maintain in good working order. So if you are producing a graphics package, then a critical use case may be: displaying a log-log plot from 2-column ascii data. If you are producing a molecular dynamics code, a critical use case may be: obtain an optimized molecular geometry for the ground state of a small molecule (like benzene or water). If you are producing an instrument simulation code, then a critical use case may be: simulate the ARCS instrument with an empty vanadium plate as the sample. Behavior tests are usually written to test a known set of results for the use cases, and these tests should be run regularly as the code is modified (to ensure code integrity).
Criteria for validation of results:
The criteria for validation state the amount of error that will be accepted in the testing. For example, a test that compares the optimized geometry for the ground state of water should predict the bond angle, bond lengths, and ground state energy within a specified accuracy of the accepted values.
Requirements and constraints:
Requirements or constraints may be things that the programmer has no or little control over. This may be that there is a external deadline on the code, and the functionality that must be developed by that date. A constraint may also be that the code is derived from a third-party code that runs only on Windows and is closed source.
Additional notes:
Add any notes here that further describe the developement plan, that there was no apparent place for in any of the above sections.
--Mike McKerns
--Tom Swain
