Functional Requirements Guidelines

Transcription

1 Functional Requirements Guidelines Introduction for software development This guidance provides descriptions of the content of the top-level headings in a functional requirements document for software development projects. Software engineers understand the word function much as mathematicians do. Both mathematical functions and program functions take inputs and process them into outputs as shown in Figure 1. Figure 1: Simple Mathematical Function Figure 1 shows the function (f) as a black box that transforms inputs (I) into outputs (O). Even the simplest program function typically has multiple inputs and multiple outputs as shown in Figure 2. Figure 2: Simple Programming Function A functional requirements document should contain all of the information that the software engineer needs to understand the functional problem at hand. The first two sections of the functional requirements document provide descriptions of the inputs and the outputs. The final Processing section describes what you know about the mapping of the inputs to the outputs without specifying how the software engineer will implement that mapping. You should limit the focus of this kind of document to the requirements for a single function. For 1 of 7

2 programs that must provide multiple functions, you should provide a functional block diagram, Figure 3, in the Overview section that shows the relations among the subordinate functions. Each function should then have its own functional requirements section. Figure 3: Sample Multi-function Block Diagram Each of those sections should use this guidance. This strategy keeps each functional requirements document or section small and focused. "Just the facts, please." as Joe Friday used to say on Dragnet. Now, let's understand what a functional requirements document is not. First, it is not a specification of how to do things. That is what the software engineer must have the liberty to decide. The requirements document describes what must be, not how it must be. Second, it is not a research project. Sometimes, you may not know the answers to questions that must be answered before you can write a functional requirements document. In that case, you should write a separate, prior, knowledge requirements document. I have provided a similar guidelines document for that kind of document separately. Inputs The Inputs section of the functional requirements document itemizes the inputs that are necessary. Unnecessary inputs should not be included. This document only covers file inputs. Software engineers consider structured and unstructured inputs to be very different artifacts and your functional requirements document should clearly distinguish them. Unusual proprietary formats also need special treatment in the functional requirements document. STRUCTURED INPUTS Typical structured inputs might be lists, tables, or databases. Lists contain a single column of data. 2 of 7

3 Tables contain multiple columns of data. A database is one or more multi-column tables that have a unique key in the first column of every record. The inputs may be formatted in a variety of ways (spreadsheets, comma-separated value [csv] text files, tab-delimited text files, XML including XHTML files, or proprietary formats). The Inputs section should describe the structure of such input artifacts and the data types each field contains, if known. If not, see the knowledge requirements guidance. UNSTRUCTURED INPUTS If unstructured inputs require processing (Word documents or HTML files), the Inputs section should list the artifacts and provide the criteria (not the method) that the software engineer should use to extract the relevant data from each artifact. If possible, provide search terms (with case-sensitive or case-insensitive qualifications). As with the structured artifacts, indicate the data types carefully. If the processing is merely a conversion of the entire content from one format to another, the Input section should carefully describe the input formats. UNUSUAL PROPRIETARY FORMATS If inputs are in unusual proprietary formats, you may be expected to provide the program that reads those formats. You should negotiate with the software engineer to decide who will be responsible for converting unusual proprietary formats to standards-based formats. If you are going to be responsible for the conversion, the original proprietary format should not be discussed in the Input section. Only describe the actual inputs that the software engineer must use. Outputs Outputs can include both files and user interface displays. This document only covers the file outputs. In addition, it does not cover unusual proprietary output formats because of the extreme expense of that kind of development effort. Each functional requirement must itemize and describe every possible output. This part of the document or section simply describes each possible output without any mention of its relation to an input or the method used to create it. However, to make the writing of the Processing section easier, the granularity of the Output section should be the same as the granularity of the Input section. For example, if the Input section describes input fields, then the Output section should describe output fields. Processing If you have provided the first two sections as described above, this section should be relatively easy 3 of 7

4 to complete. You can fully describe the processing that the prospective program must perform by providing one or more input-to-output maps. However, providing those maps requires functional analysis. If you are comfortable performing that analysis yourself, the Functional Analysis paragraphs below are just for your information. If you would prefer to consult with me interactively to perform and document that analysis, the Functional Analysis paragraphs below will set your expectations for that interaction. FUNCTIONAL ANALYSIS Input-output mappings come in only the following flavors: One-to-one (1-1) One-to-many (1- ) Many-to-one ( -1) Many-to-many ( - ) As you know, in mathematics, functions only provide 1-1 and -1 mappings. Every function gives one and only one result for any set of inputs. Programing functions, on the other hand, have to cover all possible mapping types. However, to ensure that the program is deterministic does not produce random outputs we need to identify one or more key inputs and a logical selection function for each of the x- mappings. The paragraphs below describe the documentation tables that permit you to express the processing requirements clearly and concisely as mappings. 1-1 MAPPINGS We have a one-to-one mapping when there is just one output for each input. For one-to-one mappings, a two-column table provides exactly what you need to express your functional analysis. For example, a program that needs to calculate the y-value on a straight line with a slope of 3 and a y intercept of 0 as shown in Table 1. Table 1: 1-1 Mapping Table Sample x y=mx-b of 7

5 1- MAPPINGS We have a one-to-many mapping when a single input generates multiple outputs. For one-to-many mappings, we need to use a multi-column table with just one column dedicated to the input values and many columns dedicated to the output values. For example, a program that needs to calculate the binary digits from a single decimal digit will have 1 input and 4 outputs as shown in Table 2. Table 2: 1- Mapping Table Sample Input (Decimal) Outputs (Binary Digits) If we take each group of 4 binary digits as a single output, we can reduce this to the 1-1 case. -1 MAPPINGS We have a many-to-one mapping when multiple inputs generate a single output. For many-to-one mappings, we need to use a multi-column table with many columns dedicated to the input values and just one column dedicated to the output values. For example, a program that needs to calculate a single decimal digit from the binary digits will have 4 inputs and 1 output as shown in Table 3. 5 of 7

6 Table 3: -1 Mapping Table Sample Inputs (Binary Digits) Output (Decimal) If we take each group of 4 binary digits as a single input, we can reduce this to the 1-1 case. - MAPPINGS We have a many-to-many mapping when multiple inputs generate multiple outputs. For many-tomany mappings, we need to use a multi-column table with many columns dedicated to the input values and many columns dedicated to the output values. For example, a program that needs to calculate 2 octal digits from several binary digits will have 4 inputs and 1 output as shown in Table 4. 6 of 7

7 Table 4: - Mapping Table Sample Inputs (Binary Digits) Output (Octal Digits) If we take each group of 4 binary digits as a single input and each pair of octal digits as a single output, we can reduce this to the 1-1 case. 7 of 7