In this section, we introduce the method for confirming quality requirements considerations in a design document by using spectrum analysis.
Overview
Figure 2 shows the overview of the method. In the method, spectrum analysis is first applied to the requirements and design respectively. We then compare one spectrum with another to identify quality characteristics defined incorrectly and/or incompletely. In Figure 2, “Qbility” seems to be defined incompletely in design because the power of “Qbility” in the design spectrum is smaller than that in the requirements spectrum. “Sbility” seems to be defined incorrectly in the design because the power of “Sbility” in the design spectrum is larger than the power in the requirements. Because we can find methods (functions in desgin) related to each characteristic on the basis of the relationships between characteristics and methods, we can investigate the causes of such incompleteness and/or incorrectness. We explain each step in this method below.
Spectrum analysis for requirements
The spectrum analysis for requirements is performed in accordance with the technique in the section “Spectrum analysis”.
Spectrum analysis for design
There are several kinds of software design documents because there are several kinds of people who read them, such as project managers, programmers, architects, and testers. We focus on a design document for programmers in this paper. We thus regard the explanations for each method or function as a design document because programmers have to know the functionalities and roles of each method or function.
The spectrum analysis for design is also performed in accordance with the technique in the section “Spectrum analysis”. Instead of a sentence(s) for each requirement, a sentence(s) used for explaining each method is used for the spectrum analysis. We thus normalize the powers in a spectrum on the basis of the number of methods.
In addition, we have to revise the spectrum in accordance with external libraries such as application programmable interfaces (API) and/or frameworks. Both external organizations and the developer him/herself will provide such external libraries. Such a revision is performed as follows.
-
1.
In accordance with the design description, external libraries to be used are selected.
-
2.
For each library, quality characteristics supported by the library are identified. We call such characteristics “library-characteristics”. The documents for each library help us to identify them.
-
3.
For each method, the libraries used in the method are identified. We then establish the relationships between the method and the library-characteristics of the libraries.
Aspect-oriented design (AOD) is currently out of the scope of this method. In the case of using AOD, the revision steps above cannot be applied because main routines do not know their required libraries (aspects), but the libraries know the routines that call the libraries. All aspects should be woven together before applying our method if AOD is used.
We show an example of a design document for programmers in Figures 3 and 4 written in Javadoc (Oracle 2004). In this example, a supporting system for a drugstore is shown, and the system will be written in Java. In this design, 13 classes are defined except test classes. In Java, test classes are normally ended with “Test” because that is the common practice when using the unit test tool called “JUnit”. In Figure 3, methods in the class “Medicine” are listed with brief explanations. However, programmers cannot implement each method with only such brief explanations because such explanations contain only the functionality of the method. Designers thus have to give more detailed explanations for each method, as exemplified in Figure 4. In the figure, the method “sell” in the class “Medicine” is explained in detail. By reading this detailed explanation, programmers can correctly implement the method. In this detailed examination, programmers can know that the sell method does not require checking the amount of stock. These kinds of explanations avoid useless double checks for parameters that are required by the policy of “design by contract” (Meyer 1997). The spectrum analysis for the design is applied to this kind of detailed explanations. Terms and words that are used in the spectrum analysis depend on the contents of the TCM. In our evaluation, the same TCM is used in both the requirements and design documents.
Comparison
We can simply visualize the spectra of both the requirements and design and identify the differences in order to find the causes of inconsistent and/or missing requirement considerations. When an engineer finds such causes, he or she modifies the design documents to remove them. We explain how to find such causes by using the example in Figure 2. As mentioned in the first sub-section of the section “Method”, we can find that “Qbility” seems to be defined incompletely in the design because its power in the design is smaller than that in the requirements. By examining the relationships at the top of the figure, methods except for methods 2 and 3 are suspected to cause the incompleteness because they are not related to “Qbility” in the figure. To remove such causes, an engineer has to establish more relationships between the quality characteristics and design than exist now. For “Sbility”, methods 3 and 10 are suspected to cause the incorrectness in the design because “Sbility” is not defined in the requirements but is defined in the design as shown in Figure 2. To remove such causes, the engineer has to establish less or no relationships between the quality characteristics and design than exist now.
Because a quality spectrum is a kind of vector, we use cosine similarity (cossim) to decide whether two spectra are similar to each other. Cosine similarity can be a metric for identifying the inconsistent and incomplete quality requirements considerations in design. The definition of cosine similarity between and is as follows.
When two vectors are completely the same, the value is 1. Because a quality spectrum never has a negative value in its vector, cosine similarity between two quality spectra varies from 0 to 1. Therefore, we may regard two quality spectra as similar if their cosine similarity is close to 1. In addition, cosine similarity does not take the length of the vector into account. Figure 5 shows an intuitive meaning of the cosine similarity with two-dimensional vectors. As show in the figure, two vectors D and C are almost the same as each other. The cosine similarity among them thus takes almost one (0.99). In comparison, vectors A and E make a right angle. As mentioned above, all values in a vector for our spectrum analysis take non-negative values. The direction of vector A is thus completely different from that of vector E. The cosine similarity between these vectors takes 0 by the definition above.