"Create one functionality module for each unique stimulus set of the functionality tree."
This begs explanation of the following:
The sentence could just as accurately be written:
"Create one functionality module for each unique behavior table."
So we need to cover:
And underlying everything is the question "What are requirements?" which is answered by:
That should be a minimum starter set. Will add more if questions and other feedback indicate a need.
The logical progression is:
We will cover one topic at a time, and will move on to the next after all questions and comments about the current topic are addressed. That way hopefully we won't loose anyone. Just to be tidy, will start the first topic, concept models, in a separate email.
As with software, there are different ways to develop a methodology.
The most straightforward way is the Edisonian approach -- try a bunch of different approaches until one is found that works noticeably better than the others, or maybe just works at all. This is where I, Grady Booch, and most others were back in the '80s. Success with the Edisonian approach was very hit and miss -- mostly miss.
A second approach is to find some notations that are useful in software development, then document a process or methodology around developing these notations. This is where Grady Booch is now with UML and RUP. The success of this approach depends on the quality of the underlying notations (or, possibly, how intensely they are marketed!)
A third approach is to find a development solution or 'design pattern' that seems to be sufficiently generic, then specify a process or methodology for building software according to that pattern. This is where both Sun and the Struts community are with processes for building enterprise systems based on the Model-View- Controller (MVC) pattern. Another example are object- oriented methodologies since OO is fundamentally a design pattern. Success of this approach depends on the genericity and suitability of the underlying pattern.
A fourth approach is to define values and principles which arguably produce better software when applied, then build a methodology around those values and principles. This is where the agile community is with methodologies such as XP and SCRUM.
A fifth way is to select a proven engineering model as a basis, then define a software engineering methodology that conforms to that model. This is what Freedom does.
A sixth way is to postulate mathematics-based formal methods for recording requirements, design, and implementation, then build a process and accompanying tool set around those formal methods. The success of this approach depends largely on the understandability of the formal methods to developers. Formal methods for implementation met with good success with the advent of assembly language, followed by spectacular success with Fortran and COBOL. The software research community has been riding this success wave ever since. However, in the areas of requirements and design, the practical success of formal methods has been nil.
The underlying concept model used in the creation of Freedom is the engineering concept of the black box. How to apply black box-based thinking to software engineering was suggested by Harlan Mills in http://csdl.computer.org/comp/mags/co/1988/06/r6023abs.htm (Unfortunately, one has to pay IEEE dues to view this paper online.)
In this paper, Mills proposes extending the black box model into a triple box-structured model consisting of black box, state box, and clear box. Freedom adopts this triple model, with some changes in semantics for the state box. Also, Freedom uses slightly different terminology of black box, gray box, and white box for the three facets of the model.
In a manner fundamentally, if not literally, consistent with Mills, Freedom uses the black box as the requirements model, the gray box as the design model, and the white box as the implementation model.
For more information on Freedom's triple models, including a graphical depiction of each, see:
black box --
http://www.jreality.com/freedom/bb_model.html
gray box --
http://www.jreality.com/freedom/gb_model.html
white box --
http://www.jreality.com/freedom/wb_model.html
The black box model is a familiar and proven concept in many engineering fields including electrical engineering, computer hardware engineering, aerospace engineering, and even behavioral psychology. Mills believed that application of the proven box-based model concept held great promise for software engineering as well. The developers of Freedom concurred when they selected Mills' box-based concept model as the foundation for Freedom.
1. Note: Since the team understood they would be stuck using the methodology if they agreed to it, they subjected it to a VERY intense peer review. The methodology survived the peer review with very little modification even though the team was free to suggest any modifications they wished. They were also free to propose any alternate methodology. No one did.
Fasten your seat belt. Here we go...
Encapsulation of requirements in code objects necessitates a change in our
perspective on requirements. Rather than viewing requirements as statements
_about_ the software, they are considered to be the external interface _of_
the software. The external interface consists of many stimulus-response
pairs organized into into cohesive sets, each set ideally containing 7+-2
stimuli. The stimulus sets are themselves organized into a functionality
tree that defines the external interface architecture. During design,
the external interface architecture becomes the upper level of the design
architecture. Within this upper level, a requirements encapsulating
functionality module is created for each stimulus set of the functionality
tree. Each functionality module contains code that:
a. creates the stimulus detection mechanisms,
b. listens for incoming stimuli, and
c. generates the responses
for one stimulus set. Changes to any requirement (external interface
stimulus-response pair) are thus localized to one functionality module,
making requirements change easier.
The change in requirements perspective enables requirements encapsulation because interfaces are encapsulatable whereas arbitrary statements are not. While requirements encapsulation is beneficial for reasons detailed below, is the prerequisite change in requirements perspective warranted? Is it justified by any theory of computer science or software engineering?
Standard black box theory states that the only information known about a system viewed as a black box is its external interface. Thus, the combination of Freedom's definition of requirements and standard black box theory results in a derived definition of requirements as "the external interface of the software system." This is exactly the definition that enables requirements encapsulation, since interfaces are encapsulatable.
First, and foremost, is that requirements specification becomes exactly identical to specification of the software system external interface, and ONLY the software system external interface. The definition excludes all other information.
Freedom specifies the external interface in terms of stimuli and associated responses, as proposed by Mills in http://csdl.computer.org/comp/mags/co/1988/06/r6023abs.htm. Thus defined, requirements are _always_ encapsulatable. (Note: for purposes of brevity, there is one exception that I am skipping here as it is not critical to an understanding of requirements encapsulation.)
In practice, the new interface-centric definition of requirements is consistent with the old standard definition of requirements -- "what the system shall do" -- because all capabilities of the system MUST be reflected in its external interface. If some were not, those capabilities could not be invoked and/or could not make their results available to the users. Thus, conceptually, nothing is lost, but much is gained, by the new definition.
The downside of the new definition is that many other disparate approaches
to requirements must all be sacrificed. Use cases, being usage processes
and not the external interface, no longer qualify as requirements, by
definition. Likewise, long lists of prose statements about the system are
also no longer eligible to be called requirements. (Also, according to Parnas,
"PROSE IS THE SIGN OF AN ERROR" (his caps)
in a requirements specification!) Using test cases as requirements is
similarly invalid since tests are not the external interface either.
Proponents of these and other previous approaches to requirements are thus
faced with a difficult choice: reject their favored requirements solution,
or reject the benefits of requirements encapsulation.
During development, the new definition of requirements needed to drive requirements encapsulation saves time and cost by replacing current requirements specification efforts with specification of the external interface. Since the external interface must be developed in any case, the current requirements effort that it replaces is time and effort saved. Also, I have found through personal experience that specification of the external interface using Freedom's techniques of functionality trees and behavior tables to be much faster and more responsive to change than alternate ways of recording 'requirements.' Also, all information in the functionality tree and behavior tables serves directly as code specification information for the requirements encapsulating functionality modules. No additional design work need be performed for the functionality modules, resulting in further time and cost savings during development.
Even greater savings accrue during maintenance. Information exists that 60-80% of all changes during maintenance are requirements changes. Since maintenance is widely acknowledged to comprise 60-80% of all software cost, simple math indicates that 36% (0.6 x 0.6) to 64% (0.8 x 0.8, or approximately one third to two thirds, of ALL software cost is due solely to requirements changes! Thus, any technique that reduces the cost of performing requirements changes, even by a modest amount, can have a dramatic effect on the total life cycle cost of software.
The greatest potential savings of all is during reuse. As demonstrated by traditional OO technology, a fringe benefit of encapsulation is improved reusability. Likewise, requirements encapsulation should permit the creation of reusable requirements encapsulating functionality modules. In the long run, libraries of functionality modules for common external interface functionality can be developed. Such functionality might include things such as login/logout, personal data capture, inventory data capture, etc. In each of these cases, not only the functionality tree and behavior tables would be reusable, but also the implementing functionality module code along with all required support code. For example, reusable login/logout requirements would contain the necessary UI components, persistent data stores for user names and passwords, and all required password encryption. Thus, reusable requirements are fully functional subsystems. With a sufficient number of reusable requirements components, the time to construct working applications could be reduced in a manner similar to, but with much greater leverage than, is the case with current reusable Design components.
In fact, many of Freedom's requirements techniques can be found loitering in various corners of the industry. For example, the stimulus cohesion ideas underlying stimulus sets are also implicit in the HTML FORMS tag. A functionality tree is basically the tabular equivalent of the AM User Interface Flow Diagram. The structure of a functionality module is identical to best accepted practice for writing Java GUI code that does NOT use inner classes (although functionality modules are not restricted to GUIs). Reusable requirements components are a functional superset and structural improvement of the web services concept.
'Interface-first" follows directly from the the black box definition of requirements and the box-based concept model upon which it is founded. Some have said that the essence of agile is its values and principles. Similarly, the essence of Freedom is its models and definitions. All other artifacts of Freedom either derive from the concepts and definitions, or at least are compatible with them.
How does one specify an external interface in Freedom? For the answer, we again turn to Harlan Mills.
Mills suggested a two-step process: (1) specify the system stimuli, and (2) specify the responses to the stimuli. To this process, Freedom adds one more step: (3) specify the protocol. In keeping with Parnas' idea of a rational process, these steps may be performed in any order, except causality requires that stimuli be identified before their responses. Thus, we shall start with identification of stimuli.
Almost.
The dictionary definition of stimulus is "anything that elicits a response."
Freedom identifies two kinds of stimuli: command stimuli and data stimuli.
Data stimuli are values with semantic meaning to the problem being solved by the program. Examples include (but are not limited to) data typed into data entry fields or onto command lines by users; data read from files or data bases; and data input from a network connection. The data may be saved, transmitted, used in a computation, or used in any way or purpose necessary and consistent with its semantic value to the problem being solved.
Command stimuli are trigger values that have no semantic meaning to the problem being solved by the program. The simplest and most common example is the value created by a button when pressed by a user. The value has no intrinsic semantics to the problem being solved; it merely acts as a signal to initiate some response.
Another example is an XML tag value, such as 'name' in the XML fragment
<name>Rick</name>
'name' has no intrinsic value to the problem being solved. We could just as easily change 'name' to 'xxx' in the DTD and it would make no effective difference. Thus, 'name' is a command stimulus. However, the value 'Rick' is a data stimulus; it cannot arbitrarily be changed to, say, 'Pete' without some profound change in the results of the program, e.g., Pete (erroneously) goes to jail instead of Rick if, say, the XML file lists convicted felons.
This example also demonstrates a common relationship among the types of stimuli: command stimuli often act as delimiters for data stimuli. This is particularly common in streaming input from sources such as formatted files (of which XML is but a special case).
Which takes us back to input. When most people use the term 'input', they are usually thinking in terms of data, i.e., 'input' and 'input data' are essentially synonymous in most people's minds. Conversely, most people do not usually associate the term 'input' with a button press (except, perhaps, developers who write lots of GUI code.) Hence, 'input' differs from 'stimuli' by 'command stimuli':
input == data
stimulus == command | data
Thus, Freedom uses the term 'stimuli' in lieu of 'input' to ensure that command stimuli are not forgotten or otherwise given short-shrift.
1. Human users
2. External system users
3. The environment
The most common mechanisms for entering human user stimuli are command lines and GUI displays. However, other sources such as voice and tactile (e.g., touch-sensitive screens) may be used in some applications. Experiments with monkeys have successfully demonstrated computer control directly via brain waves, so who knows what programming challenges human user interfaces of the future may pose! For now, let's just be content with the "simplicity" of GUIs and command lines.
External system stimuli are stimuli that originate in some system black box external to our black box. The external black box may or may not be another software system; we don't know or care (that's what we mean by saying it's 'black.') What we must know and do care about is the exact format with which to communicate with that other black box. The stream from the other system is expressed as a sequence of command and data stimuli in some particular format, or protocol. It may arrive via transmission carrier mechanisms such as wire (network, TV cable) or wireless (satellite, RF, microwave). These are all examples of stimuli from external system users.
Stimuli from the environment are used to measure natural data such as wind speed, temperature, pressure, stress, presence of physical objects, or the simple passage of time, when such stimuli are of significance to the problem being solved. Usually, the mechanisms for producing environment stimuli are sensors of various kinds, with appropriate A/D converters when necessary.
Freedom uses multiple organizational strategies to help people more effectively deal with large numbers of stimuli. The first such strategy is to organize the stimuli into groups or sets based on cohesion. The second strategy is to organize the sets of stimuli into a tree-like structure called a functionality tree. Functionality trees will be covered in the next post. Here, we will consider grouping of stimuli into sets based on their cohesion.
While there are at least seven commonly recognized types of cohesion, it is generally sufficient to consider only three types when grouping stimuli into sets:
In the case of stimuli, all the stimuli in a given set will will usually exhibit ALL of the above three types of cohesion, not just one. This is much stronger cohesion than is typically found in many situations when only one kind of cohesion is in play. Yet, achieving triple-high levels of cohesion is easy in external interfaces because such cohesion occurs naturally in that context.
Recall a stimulus set is a collection of stimuli that is functionally, physically, and temporally cohesive. Stimuli are command and data inputs, but only inputs; never outputs. So we are looking for command and data inputs that relate to the same function, are active at the same time, and are physically co-located. The last attribute is especially amenable to visual searching -- look for stimuli (command and/or data inputs) that physically group together. Several are apparent.
Quick quiz 1: What kind of stimuli are these?
The six stimuli are also temporally cohesive because they all are, or can be, active at the same time. Mouse-pressing each one is sufficient to demonstrate they are all active at the same time.
Finally, the six stimuli are (or should be) functionally cohesive.
Quick quiz 2: What is the operation, task, or object that binds the six stimuli together functionally?
To answer these questions, ask two other questions:
1. Are any command or data inputs present? If so,
2. How do they group based on physical, functional, and temporal cohesion?
Analyzing the pdf display region to the right in this manner:
1. Are any command or data inputs present?
Yes, there is a vertical scrollbar as part of the region. Under some circumstance, a horizontal scrollbar can also appear.
2. How do they group based on physical, functional, and temporal cohesion?
The scrollbars are physically in the same region panel, have the same function, and are (or can be) active at the same time. Thus, the right region consists of only one stimulus set of two scrollbars, either of of which may or may not be active depending on the relative dimensions of the pdf content being displayed.
1. Are any command or data inputs present?
Yes, a scrollbar and two tabs labeled Thumbnail and Bookmarks. Also, in the upper right corner of the region is a choice menu labeled Thumbnail.
2. How do they group based on physical, functional, and temporal cohesion?
Experiment to explore the nature of the cohesion attributes. Clicking a tab displays a separate scrollbar for each tab, and also a different choice menu. The Bookmarks tab has a choice menu labeled Bookmark. So there are more stimuli than were first apparent, with temporal cohesion coming into play to mask some of them based on the tab selected. This temporal cohesion, along with associated physical cohesion, imply two stimulus sets (SS) in the left region:
a. A Thumbnail SS consisting of a scrollbar and a choice menu.
b. A Bookmarks SS consisting of a scrollbar and a choice menu.
When the Thumbnail tab is clicked, a list of page icons appears in addition to the scrollbar and a choice menu. Are these part of the stimulus set?
Answer, apply the two questions:
1. Are they stimuli (command or data inputs)?
Yes, we can click on them and a response happens (the displayed pdf page changes). They _are_ stimuli.
2. How do they group based on physical, functional, and temporal cohesion?
All the page icons are physically together, active at the same time, and do the same thing (jump to a new page). They are in the same stimulus set.
Are they in the same SS as the Thumbnail scrollbar and choice menu, or in their own SS?
Again, experiment and evaluate against the cohesion criteria. What does the choice menu do? It causes the page icons to change size, which in turn has an influence on the scrollbar size. So the choice menu and scrollbar are functionally related to not only each other but the page icons. Also, the choice menu, scrollbar, and page icons are all temporally cohesive (active when the Thumbnail tab is selected, disabled when the Bookmarks tab is selected) and physically cohesive (all on the same Thumbnail panel).
Conclusion: The page icons are all in the Thumbnail stimulus set along with the scrollbar and a choice menu. They are not in their own SS since they do not differ wrt functional. physical, or temporal cohesion. Hence, a more complete stimulus set description of the left region would be:
a. A Thumbnail SS consisting of a scrollbar, choice menu, and page icons,
b. A Bookmarks SS consisting of a scrollbar, choice menu, and bookmark icons (by analogy to the Thumbnail case; the file I am displaying does not have bookmarks in it to experiment with.)
Oops! One more detail before leaving the left region. Didn't we forgot to list the Thumbnail tab in the Thumbnail SS, and the Bookmarks tab in the Bookmarks SS?
Actually, no. The two tabs activate the stimuli in their respective stimulus sets, but are not themselves in those stimulus sets. Logically, clicking them when their respective SS is already displayed should have no effect or, better, the tabs should be disabled when its SS is already displayed. (Note: this is not the actual case however. Clicking a tab when its SS is already displayed makes the entire left region disappear! Adobe may claim this a feature, but SS analysis plus the principle of Least User Surprise all say it is a bug.) Thus, the tabs are not (or should not be) temporally cohesive with the stimuli in their regions. Also, they are not physically cohesive as they lay outside the panels they activate. Finally, they have a different function. While the function of the panels is to control page navigation, the function of the tabs is to control selection of the page navigation panels. As a result, the tabs are not part of the two left region stimulus sets, but are in fact their own SS:
c. A page navigation panel selection SS consisting of two tabs labeled Bookmarks and Thumbnail.
This does not complete the stimulus set analysis of the AAR program by any means. It is just the beginning. However, it should be enough to get a basic feel for what stimulus sets are in a practical sense rather than just a theoretical sense. Readers are encouraged to find other stimulus sets on their own using the definitions and techniques described above, and to ask questions about any new wrinkles they encounter.
I suspect the name "New Stimulus Response" was coined when the functionality tree notation was being developed because it is in that context that the term is most descriptive. When stimulus sets are arranged into a tree-like structure, the criteria used to arrange them is the New Stimulus Response, specifically, the activation of additional stimulus sets. Stimulus set activation is the only aspect of the NSR depicted in a functionality tree; stimulus deactivation is specified in behavior tables.
Functionality trees may be created using simple text editors that use fixed-pitch fonts (e.g., tty or courier), or spreadsheets, as such tools maintain the column alignments while also making it easy to insert new rows. The following is a sample generic functionality tree. Note that your reader must use fixed-pitch fonts for the example to appear properly; proportional pitch fonts will destroy the column alignment. If this happens, try viewing the html version of this post at http://www.jreality.com/freedom/papers/req_encap/posts.html
Sample Functionality Tree
Level 0 Level 1 Level 2
SS 0-A SS 1-A
-------- --------
stim 0-1 stim 1-1
SS 2-A
--------
stim 1-2 stim 2-1
stim 2-2
stim 2-3
stim 2-4
SS 1-B
--------
stim 0-2 stim 1-3
stim 1-4
stim 1-5
stim 0-3
Note: "SS" means "stimulus set"
"stim" means "stimulus"
In the above simple example, the external interface consists of four stimulus sets, labeled generically as SS 0-A, SS 1-A, SS 1-B, and SS 2-A. (Note that in a real example, the stimulus sets and stimuli would have names that are semantically meaningful to the application. However, a functionality tree does not care what the names are, so generic names are used here for illustrative purposes only.)
The functionality tree shows that the four stimulus sets consist of the following stimuli:
SS 0-A SS 1-A SS 1-B SS 2-A
-------- -------- -------- --------
stim 0-1 stim 1-1 stim 1-3 stim 2-1
stim 0-2 stim 1-2 stim 1-4 stim 2-2
stim 0-3 stim 1-5 stim 2-3
stim 2-4
The tree structure of the functionality tree depicts the activation of the four stimulus sets, as follows.
1. When the application is first launched, only the stimuli shown at Level 0 are active. Hence, SS 0-A is the only stimulus set active when the program is launched.
2. If stim 0-1 is received, part of its externally-visible response is to activate SS 1-A.
3. If stim 0-2 is received, part of its externally-visible response is to activate SS 1-B.
4. If stim 0-3 is received, it does NOT activate any additional stimuli.
5. If stim 1-2 is received, part of its externally-visible response is to activate SS 2-A. Note that stim 1-2 cannot be received until stim-0-1 is received. (Why?)
Thus, the semantics of a functionality tree defines:
1. All stimulus sets
2. The stimuli that comprise each stimulus set
3. Which stimuli activate which other stimulus sets,
i.e., partial New Stimulus Set response.
The semantics of a functionality tree does NOT specify:
a. Stimulus deactivatation
b. Stimulus activation in addition to the indicated stimulus set(s)
b. Any response other than stimulus set activation.
All of these semantics, and more, are the responsibility of the behavior table notation.
Likewise, a functionality tree is independent of the technology used to detect stimuli -- GUI event handling, network signal detection, environment sensors, etc make no difference to a functionality tree.
As a result, a functionality tree is a notation for specifying stimuli and their organization in a implementation-independent manner. In this respect, a functionality tree is analogous to an electrical schematic. Both depict essential characteristics of a design without specifying the details of the implementation. Hence, a functionality tree serves much like an "external interface schematic."
Recall from Post 3 that the uppermost menu bar containing the stimuli File, Edit, Document, View, Window, and Help was a stimulus set, For lack of a better name, let's call this stimulus set "Main Opts". Since it is active when AAR is first launched, Main Opts appears in the leftmost (Level 0) column of the AAR functionality tree:
AAR Functionality Tree
Level 0
Main Opts
---------
File
Edit
Document
View
Window
Help
Note that other stimulus sets are also active at start up. These would also appear in the Level 0 column in the full AAR functionality tree. In order to keep the example simpler (and this post shorter), we will ignore these other stimulus sets and focus only on Main Opts.
When the File stimulus is activated by clicking it with the mouse, a popup menu appears. This popup menu is a new stimulus set, and its menu items are new stimuli. Let's call this new stimulus set "File SS" (short for File Stimulus Set) since it is a stimulus set activated by the File stimulus. File SS contains the stimuli Open, Close, Save A Copy, Document Properties, Document Security, Page Set Up, Print, history list, and Exit. Since File SS is activated by a Level 0 stimulus, File SS appears in the functionality tree (FT) at the next level down (Level 1):
AAR Functionality Tree
Level 0 Level 1
Main Opts File SS
--------- -------------------
File Open
Close
Save A Copy
Document Properties
Document Security
Page Set Up
Print
history list
Exit
Edit
Document
View
Window
Help
The fact that File SS is activated by the File stimulus is denoted by placing the first stimulus of File SS (Open) immediately to the right of the activating stimulus (File).
Examining the stimuli in File SS reveals that Document Properties activates yet another stimulus set consisting of three stimuli. This stimulus set, which we will call Document Properties SS, appears at the next level down (Level 2) from its activating stimulus (Document Properties):
AAR Functionality Tree
Level 0 Level 1 Level 2
Main Opts File SS
--------- -------------------
File Open
Close
Save A Copy
Document Properties SS
----------------------
Document Properties Summary
Fonts
Embedded Data Objects
Document Security
Page Set Up
Print
history list
Exit
Edit
Document
View
Window
Help
Experimenting with Document Properties SS stimuli reveals that Summary and Fonts both cause a popup window to be displayed. These windows are primarily for information display. If all they contained was displayed information with which the user could not interact, they would not be stimulus sets because they would not contain any sources of stimuli. However, each of these windows contains a button to hide the window, and the Fonts window contains a second button to control the information displayed. The existence of these stimuli make these windows stimulus sets also.
Expanding the Document Properties SS to include the stimulus sets it activates grows the FT further:
AAR Functionality Tree
Level 0 Level 1 Level 2 Level 3
Main Opts File SS
--------- -------------------
File Open
Close
Save A Copy
Document Properties SS Summary SS
---------------------- ----------
Document Properties Summary OK
Fonts SS
--------------
Fonts OK
List All Fonts
Embedded Data Objects
Document Security
Page Set Up
Print
history list
Exit
Edit
Document
View
Window
Help
We may now wish to consider that, if Summary and Font activated popup window stimulus sets, some of the stimuli at Level 1 may also. Further investigation reveals this is true. In fact, some of these Level 1 triggered popup windows are heavily laden with stimuli. For example, the window triggered by the Open stimulus has three buttons, two lists, and two text fields. Adding the stimulus sets activated by the other Level 1 stimuli fills the tree out much more:
AAR Functionality Tree
Level 0 Level 1 Level 2 Level 3
Main Opts File SS Open SS
--------- ------------------- ----------------
File Open Directories list
Files list
Filter
Selection
Open
Apply
Cancel
Close
Save A Copy SS
--------------
Save A Copy Directories list
Files list
Filter
Save As
Optimize
OK
Apply
Cancel
Document Properties SS Summary SS
---------------------- ----------
Document Properties Summary OK
Fonts SS
--------------
Fonts OK
List All Fonts
Embedded Data Objects
Document Security SS
--------------------
Document Security OK
Page Set Up SS Paper SS
-------------- --------
Page Set Up Paper Letter
Tabloid
Ledger
Legal
Executive
A3
A4
A5
B4
B5
Other
Scale
Width
Height
Portrait
Landscape
OK
Cancel
Print SS
--------
Print Printer
Command
File
File Name
Browse SS
---------
Browse Directories list
Files list
Filter
Selection
OK
Apply
Cancel
- - - -
All
From
From page
To page
Odd
Even
Selected Thumbnails
Selected Graphic
Reverse Order
Comments
- - - -
Shrink...
Expand...
Optimize for Speed
Download Asian Fonts
Save Printer Memory
Language Level 1
Language Level 2
Language Level 3
- - - -
OK
Cancel
history list ***EXERCISE***
Exit
Edit
Document
View
Window
Help
1. Which stimuli are text fields?
2. Which stimuli are buttons?
The answer is -- we cannot answer such questions using the above functionality tree (try it). In the process of creating the functionality tree, we lost implementation-specific information. It is true that we could have captured some. For example, instead of listing a stimulus as
OK
we could have listed it as
OK Button
We did not do this because to do so would have violated a functionality tree guideline:
When creating a functionality tree, try to avoid using names that imply an implementation mechanism such as Button, Text Field, Choice List, etc. In the AAR FT we do use the term 'list', but only in a generic sense to mean a 'variable list of stimuli'. This use of 'list' does not imply a GUI List component or any other specific implementation mechanism.
By keeping functionality trees generic, they are better able to fulfill their role as a schematic of the external interface that identifies stimuli and their organization without specifying any particular implementation. To press the point a bit further, the following two questions should be just as legitimate (and just as unanswerable) as the first two:
3. Which stimuli are XML tags?
4. Which stimuli are hardware toggle switches?
Nothing in the functionality tree should rule out these possibilities, nor be biased toward them. When functionality trees are created to be generic, the requirements of the system become more generic as well. They may describe a hardware system or software system. They may be implemented using archaic or bleeding edge interface technology. It is the job of notations such as functionality screens (sketches of the UI) and interface protocol descriptions to specify the implementation-specific aspects of the requirements, i.e., the "form" of the interface. The purpose of the functionality tree and associated behavior tables is to specify only the raw functionality, or "function," of the system without prejudice to either the source of the stimuli or implementation technology.
One advantage of making functionality trees generic is that it promotes focusing of the team's mental energy on the functionality needed by the customer without diverting excessive amounts of thought to detailed implementation issues. Of course, some thought must be given to the implementability of the functionality, e.g., we do not want to specify requirements that are excessively expensive, or even impossible, to implement. This means it is usually a good idea to start developing functionality screens (sketches) and protocol format descriptions in parallel with the functionality tree. The result of such parallel development can be a more robust and generic functionality tree. Any thoughts about how to implement the functionality can be recorded immediately in the proper notation, thus reducing any urge to place such information in the FT. The primary focus of the team early-on when the functionality tree is first being developed should be on the raw functionality required, not on specific protocols. The implementation protocols can be refined after the requirements architecture and functionality specified by of the FT become less fluid.
Another observation regarding functionality trees is that the notation is very amenable to change, including expansion. Note that in the AAR example we started small and easily grew the FT in increments by adding one or a few stimulus sets at a time. This approach works well in actual development as well. It is not necessary, or even possible in many cases, to create the "complete" FT at once. This is never a problem since functionality trees can easily be expanded to incorporate new requirements as they are identified, even if that turns out to be years later during maintenance (or evolution) of the system. Because it is so easy to change, a functionality tree is a convenient notation for recording requirements on projects that employ incremental and/or evolutionary development approaches.
As a self-check, I have left the 'history list' stimuli unexpanded so that you can give the technique a try for yourself. In order to expand the 'history list' part of the tree, you should first view several pdf files with AAR in order to build a list of names in the history list to experiment with. To do a more complete job of experimentation, try deleting or moving one of the pdf files (using operating system commands) after viewing it so AAR cannot find it when you click on its name in the history list.
If you think of any questions while expanding the 'history list' part of the tree, please ask. It is very possible that others in the group will have similar questions.
This exercise serves an additional purpose beyond a self-check. It is a lead-in to the the next post, Post 5. However, why this is so will not be apparent until you try it. Have fun!
AAR Functionality Tree
Level 0 Level 1 Level 2
Main Opts File SS
--------- -------------------
File Open
Close
Save A Copy
Document Properties
Document Security
Page Set Up
Print
history list ***EXERCISE***
Exit
Edit
Document
View
Window
Help
Experimenting with the history list stimuli as part of performing the history list expansion reveals that a history list stimulus has an extensive NSR response -- an entire new instance of AAR is launched in a separate window.
How do we deal with this in the functionality tree? One approach is to replicate the entire functionality tree to the right of the 'history list" stimuli, like so:
AAR Functionality Tree
Level 0 Level 1 Level 2 Level 3
Main Opts File SS
--------- -------------------
File Open
Close
Save A Copy
Document Properties
Document Security
Page Set Up
Print
Main Opts File SS
--------- -------------------
history list File Open
Close
Save A Copy
Document Properties
Document Security
Page Set Up
Print
history list ***EXERCISE***
Exit
Exit
Edit
Document
View
Window
Help
Edit
Document
View
Window
Help
However, this approach quickly leads to trouble since the history list expansion needs to be replicated yet again, and again, and again, ... The problem is infinitely recursive.
Fortunately, there is an easy way to handle such cases. The solution is to expand the functionality tree using a referential placeholder:
AAR Functionality Tree
Level 0 Level 1 Level 2
Main Opts File SS
--------- -------------------
File Open
Close
Save A Copy
Document Properties
Document Security
Page Set Up
Print
Main Opts
---------
history list (reused SS)
Exit
Edit
Document
View
Window
Help
In the above (correct) example, the name of the Main Ops stimulus set
is placed to the right of the 'history list' stimuli (since a history
list stimulus triggers the Main Ops stimulus set), but its stimuli are
not explicitly listed. In their place, a note is inserted indicating
that this is a reused instance of a stimulus set that has been defined
previously.
There are several advantages to this approach:
1. Mechanical recording problems associated with recursion are avoided.
2. Any future changes to the stimuli in the explicit Main Ops stimulus set definition at Level 0 are automatically "inherited" by the stimulus set to the right of 'history list' (as well as by any other Main Ops references, regardless of where they may occur), making maintenance of the functionality tree easier.
3. The referential placeholder serves as an indication that the referenced stimulus set has greater than single-use utility, i.e., the stimulus set may be a candidate for requirements reuse.
A repetitive stimulus set is a stimulus set that can be activated by stimuli in two or more different stimulus sets of an application.
A reusable stimulus set is a stimulus set (SS) that is activated by stimuli in two or more different application programs. (Note: different physical instances of the SS are typically activated.)
A reusable stimulus set may also be repetitive, that is, it may, if desired, be activated from multiple stimulus sets of the same application. However, a repetitive stimulus set is not necessarily reusable, i.e., just because a stimulus set is activated from multiple places in a single application does not necessarily imply it will have utility in an entirely different application.
As an example, consider the Main Ops stimulus set above. It is clearly repetitive due to being activated by stimuli in two different stimulus sets. However, is it reusable? That is, is the entire AAR application useful as a subtree in an entirely different application program? It certainly could be. For instance, it is easy to envision a mail reader which invokes AAR to read pdf files sent as attachments. How easy this may be in practice depends on the implementation details of the AAR application in general, and the programmatic invocation interface to the Main Ops stimulus set in particular. One would have to have programming level documentation to AAR to determine if Adobe implemented AAR in a way that promoted easy reuse from other applications.
Had Adobe used a functionality tree to design the AAR external interface, one of the first clues that AAR might be a candidate to implement as a reusable component is the fact that Main Ops is repetitive in the functionality tree. While not all repetitive stimulus sets are reusable, all reusable stimulus sets are repetitive across different applications. Hence, the fact that a stimulus set is repetitive within a single application serves as a flag that the stimulus set should be evaluated more closely for possible utility as a reusable stimulus set.
Repetitive stimulus sets are significant in another respect as well. As we shall see in the next post, repetitive stimulus sets influence the number of behavior tables that need to be specified.
Responses may be characterized by their visibility, desirability, and prescriptiveness.
There are two kinds of responses based on their visibility: external internal. External responses are detectable outside the software system black box, and therefore are part of the system's requirements information set. Internal responses are not detectable outside the software system black box, and thus are part of the system's design and implementation information sets.
There are two kinds of responses based on desirability: normal and error responses. Normal responses are the expected response to a stimulus in normal operation. Error responses are undesirable or exceptional responses, and generally indicate a deviation from normal operation.
Freedom explicitly recognizes a subtype of normal response, called a new stimulus response (NSR). NSR is treated as a separate category of normal response due to its special relevance to the functionality tree and stimulus set organization, as noted in the previous post. A NSR is always an external response, i.e., it is always part of the requirements information. (Note: An Error NSR response is also a logical possibility, but is not significant enough to warrant a separate type.) This results in a total of three types of responses based on desirability: normal, NSR, and error.
There are two kinds of responses based on prescriptiveness: binding and guidance. Binding responses are specified by the customer, and must be implemented by the developers exactly as specified unless a change to the response is explicitly agreed to by the customer.
Guidance responses are specified at the discretion of the development team. They may be changed at will by the development team using whatever specification control mechanisms the team desires or, perhaps, is imposed on the team by a project management methodology external to Freedom. As far as Freedom is concerned, guidance responses are completely non-binding on the development team and need not be implemented as specified, or need not be implemented at all. The only important responses to Freedom are the binding responses. Providing the binding responses are met, any non-binding response may be used in support at the complete discretion of the development team.
Unexpanded attributes:
Visibility Desirability Prescriptive
---------- ------------ ------------
external normal binding
internal NSR guidance
error
Expanded attributes (Classification List):
Visibility Desirability Prescriptive Response Category
---------- ------------ ------------ -----------------
external normal binding Normal
external normal guidance invalid, requirements always binding
external NSR binding NSR
external NSR guidance invalid, requirements always binding
external error binding Error
external error guidance invalid, requirements always binding
internal normal binding D&I Constraint, normal
internal normal guidance D&I Guidance, normal
internal NSR binding invalid, NSR always external
internal NSR guidance invalid, NSR always external
internal error binding D&I Constraint, error
internal error guidance D&I Guidance, error
Response Classification List:
Visibility Desirability Prescriptive Response Category
---------- ------------ ------------ -----------------
external normal binding Normal
external NSR binding NSR
external error binding Error
internal normal binding D&I Constraint, normal
internal normal guidance D&I Guidance, normal
internal error binding D&I Constraint, error
internal error guidance D&I Guidance, error
In addition, the BT contains a column for Performance-Accuracy-Precision (PAP) attributes of the response. Performance includes any time restrictions on the response, such as maximum time to respond, or required periodicity. Accuracy includes requirements relating to maximum allowed deviation from a correct answer. For example, NP-incomplete problems such as the 'traveling salesman' shortest path problem are not solvable in reasonable amounts of time, but may be solvable rapidly if, say, a 20% deviation from the true shortest path is allowed. Precision relates to requirements such as number of significant digits in a result, or if an integer result is acceptable rather than a floating point result.
The general format of a behavior table is:
Behavior Table for SS _____
D&I D&I
Stimulus Normal NSR Error Constraint Guidance PAP
-------- -------- -------- -------- ---------- -------- --------
stimulus
-------- -------- -------- -------- ---------- -------- --------
:
-------- -------- -------- -------- ---------- -------- --------
stimulus
-------- -------- -------- -------- ---------- -------- --------
As the above format shows, each behavior table defines responses to all the stimuli in a single stimulus set. Each row of the behavior table specifies the response to one stimulus.
The above table merges normal and error responses for internal (Constraint and Guidance) responses since these are of less significance to requirements specification than external responses. These columns may be expanded to segregate normal and error internal responses if desired.
Finally, because a behavior table is created for each _unique_ stimulus set in the functionality tree, one behavior table represents all instances of a repetitive or reusable stimulus set. It makes no difference how many instances of the stimulus set there may be, or which functionality tree (application program) it may occur in, only one behavior table need be defined for a repetitive or reusable stimulus set.
For our example, we will focus on the Level 0 Main Ops stimulus set of the AAR functionality tree:
AAR Functionality Tree
Level 0 Level 1 Level 2
Main Opts File SS
--------- -------------------
File Open
Close
Save A Copy
Document Properties
Document Security
Page Set Up
Print
Main Opts
---------
history list (reused SS)
Exit
Edit SS
-------------------
Edit ...
Document SS
-------------------
Document ...
View SS
-------------------
View ...
Window SS
-------------------
Window ...
Help SS
-------------------
Help ...
A minimal BT showing the basic NSR responses can be created directly from the functionality tree:
AAR Behavior Table for Main Opts SS
D&I D&I
Stimulus Normal NSR Error Constraint Guidance PAP
-------- -------- -------- -------- ---------- -------- --------
File
activate File SS
-------- -------- -------- -------- ---------- -------- --------
Edit
activate Edit SS
-------- -------- -------- -------- ---------- -------- --------
Document
activate Document SS
-------- -------- -------- -------- ---------- -------- --------
View
activate View SS
-------- -------- -------- -------- ---------- -------- --------
Window
activate Window SS
-------- -------- -------- -------- ---------- -------- --------
Help
activate Help SS
-------- -------- -------- -------- ---------- -------- --------
Experimentation with these six stimuli shows no other externally detectable response. However, one addition is needed to complete this BT.
All behavior tables may optionally include an initialization stimulus. The response to the initialization stimulus is any action taken by the stimulus set as a direct result of its activation. The initialization stimulus is associated with the activation relationship of the FT, and is not usually shown as an explicit stimulus in the functionality tree. It appears explicitly in the BT if a specific response is associated with activation. If there is no activation response, the initialization stimulus need not appear in the BT.
In the case of AAR, experimentation shows that including the name of a pdf file on the command line from which AAR is run results in that pdf file being displayed on AAR start up. There are a couple different ways this can be handled in Freedom, but the simplest for our example is to treat this response as an initialization response of Main Ops:
AAR Behavior Table for Main Opts SS
D&I D&I
Stimulus Normal NSR Error Constraint Guidance PAP
-------- -------- -------- -------- ---------- -------- --------
init INPUT
pdf_file
pdf_file_name
pdf_file_content
IF pdf_file_name specified
IF pdf_file is found and valid
display Main Ops
activate Right Display Region SS
activate Left Display Region SS
show pdf_file_content in Right Display Region 1.0 sec max
ENDIF
IF pdf_file not found or invalid
activate File Error SS
display Main Ops
ENDIF
ENDIF
IF pdf_file_name not specified
display Main Ops
ENDIF
-------- -------- -------- -------- ---------- -------- --------
File
activate File SS
-------- -------- -------- -------- ---------- -------- --------
Edit
activate Edit SS
-------- -------- -------- -------- ---------- -------- --------
Document
activate Document SS
-------- -------- -------- -------- ---------- -------- --------
View
activate View SS
-------- -------- -------- -------- ---------- -------- --------
Window
activate Window SS
-------- -------- -------- -------- ---------- -------- --------
Help
activate Help SS
-------- -------- -------- -------- ---------- -------- --------
Now the BT is starting to look more interesting. Let's look more closely at the initialization response behavior:
D&I D&I
Stimulus Normal NSR Error Constraint Guidance PAP
-------- -------- -------- -------- ---------- -------- --------
01 init INPUT
02 pdf_file
03 pdf_file_name
04 pdf_file_content
05
06 IF pdf_file_name specified
07 IF pdf_file is found and valid
08 display Main Ops
09 activate Right Display Region SS
10 activate Left Display Region SS
11 show pdf_file_content in Right Display Region 1.0 sec max
12 ENDIF
13 IF pdf_file not found or invalid
14 activate File Error SS
15 display Main Ops
16 ENDIF
17 ENDIF
18 IF pdf_file_name not specified
19 display Main Ops
20 ENDIF
-------- -------- -------- -------- ---------- -------- --------
Line 6:
The conditional nature of the response is captured using a typical IF clause. (Let's call it a 'clause' not a 'statement' because we are not programming here, but capturing behavior using what amounts to structured English.) The phrase after the IF denotes some _externally-visible_ condition, in this case the existence of a file name associated with launching AAR. Checking for this file name is part of normal operation, so the statement is aligned with the Normal external response column.
Lines 7-12:
If the file is found and is a valid pdf file, Main Ops is displayed and the Left and Right Display Region SSs are activated. (Note: Main Ops has already been activated because we are responding to its initialization stimulus. It merely remains to make it visible.) The content of the pdf file is then displayed in the Right Display Region. See post 3 for a discussion of the Right and Left Display regions.
For the sake of illustration, we pretend the customer specified that the time to launch AAR with a pdf file specified not exceed the time to launch without a pdf file specified by more than 1 second. This requirement is captured by associating a Performance requirement of 1.0 second maximum with the 'show pdf file content' response.
Notice that the response behavior clauses are phrases of the form "verb noun" or "action quantity" or "operation object", and are NEVER prose. This form results in response behavior clauses that are clear and succinct. Following these form guidelines will help produce behavior clauses that:
Lines 1-4:
Freedom's response recording convention is to list, at the top of the behavior spec for each stimulus, INPUT, OUTPUT, and LOCAL quantities referenced by the response behavior clauses for the stimulus. The quantity names specified under the INPUT, OUTPUT, and LOCAL headings should be used consistently throughout the behavior specification clauses. This helps avoid referring to the same quantity be multiple names, which can lead to confusion and misunderstandings.
When listing the quantities, it is very important to subject each quantity to a test:
"Is this quantity externally visible?"
If the answer is "no", i.e., the quantity is internal to the black box, then that quantity must appear in the LOCAL list, and any clauses it appears in must _not_ appear in any external response column; they may only appear in a Constraints or Guidance column. If the quantity was defined by the customer as implementation direction, the quantity and all clauses it appears in are listed under the D&I Constraints column and are binding, If it was defined by a developer, it and all clauses it appears in are listed under the Guidance column and are non-binding. Thus, explicitly listing all quantities as INPUT and OUTPUT (external) or LOCAL (internal) helps avoid the serious error of inadvertently specifying internal responses as requirements.
Lines 13-16
If the file is not found or is not a valid pdf file, the File Error stimulus set is activated. Main Ops is then displayed. Since there is no valid pdf file specified, the Left and Right Display Regions are not activated.
Note that activation of the File Error SS is both an Error and an NSR response. Since its status as a NSR is clear, we list it in the Error external response column to highlight its exceptional nature.
Line 18-20:
If no file name is specified on AAR start up, the response is simply to display Main Ops.
The File Error SS consists of a single stimulus labeled "OK". Also, the stimulus set is activated from the initialization stimulus of Main Ops. This results in the following revised FT:
AAR Functionality Tree
Level 0 Level 1 Level 2
Main Opts File Error SS
--------- -------------
init OK
File SS
-------------------
File Open
Close
Save A Copy
Document Properties
Document Security
Page Set Up
Print
Main Opts
---------
history list (reused SS)
Exit
Edit SS
-------------------
Edit ...
Document SS
-------------------
Document ...
View SS
-------------------
View ...
Window SS
-------------------
Window ...
Help SS
-------------------
Help ...
The above makes the FT consistent with the BT, so nominally all is well. However, explicit appearance of a stimulus set initialization stimulus in the FT is a warning flag that the requirements specification may not be quite right. This is, in fact, the case. The above FT is an over-simplification of the actual FT for AAR, intended to keep the posts shorter, less complex, and less confusing. The need to list init in the FT is the result of my having omitted something that would be important were we seriously attempting to model the AAR requirements. The omission is this:
Main Ops does not really occur at Level 0, i.e, it is not the first stimulus set to become active when AAR is launched. The first stimuli that AAR is primed to detect are command line arguments -- another set of human user stimuli totally separate from the GUI. The pdf_file_name quantity in the Main Ops BT is received in the form of stimuli (input) from the command line. The AAR command line arguments form a command-data protocol that results in another entire sub-branch of the FT, starting at the real Level 0. The activation of Main Ops is part of the response to one or more of these command line stimuli. So is activation of File Error SS. In fact, most if not all of the Main Ops init responses are properly responses to command line stimuli, and not the Main Ops init stimulus. Where the command line part of the FT completed, the need for including the Main Ops init response in the Main Ops BT would likely disappear. There would also be no need to include init in the FT, thus lowering the warning flag that something was amiss.
However, this omission and the resulting anomalies did not prevent the above behavior table from serving its instructional purpose, and probably helped. It afforded an opportunity to introduce the init stimulus and associated issues. The response clauses to the init stimulus provided a representative picture of Freedom's response behavior recording syntax and conventions.
What is strongly recommended is to keep the following guidelines in mind when adopting a response recording notation. A response behavior recording notation should:
a. be understandable to customers;
b. reduce the 'conceptual distance' to implementation for developers;
c. greatly reduce, if not eliminate, the need to 'wordsmith';
d. reduce the potential for ambiguity and misinterpretation;
e. avoid the use of multiple terms for the same quantity; and,
perhaps most importantly,
f. provide mechanisms to help avoid specification of internal behavior
as requirements.
To better illustrate application of this design rule, we turn to the functionality tree for Adobe Acrobat Reader (AAR) 5.08. A composite of all the AAR functionality tree fragments developed in previous posts is shown below. Since the design rule focuses on stimulus sets rather than stimuli, all stimuli that do not activate additional stimulus sets have been left out so as to simplify the functionality tree.
AAR Functionality Tree (partial, most stimuli not shown)
Level 0 Level 1 Level 2 Level 3
Main Opts File SS Open SS
--------- ------------------- ----------------
File Open ...
Save A Copy SS
--------------
Save A Copy ...
Document Properties SS Summary SS
---------------------- ----------
Document Properties Summary ...
Fonts SS
--------------
Fonts ...
...
Document Security SS
--------------------
Document Security ...
Page Set Up SS Paper SS
-------------- --------
Page Set Up Paper ...
...
Print SS Browse SS
-------- ---------
Print Browse ...
...
Main Opts
---------
history list (reused SS)
,,,
Edit SS
-------------------
Edit ...
Document SS
-------------------
Document ...
View SS
-------------------
View ...
Window SS
-------------------
Window ...
Help SS
-------------------
Help ...
The above FT can be simplified further by showing only the stimulus set names. This makes the stimulus set activation structure (defined by the New Stimulus Set Responses) of the FT more apparent.
AAR Functionality Tree (partial, stimulus sets only)
Level 0 Level 1 Level 2 Level 3
Main Opts File SS Open SS
Save A Copy SS
Document Properties SS Summary SS
Fonts SS
Document Security SS
Page Set Up SS Paper SS
Print SS Browse SS
Main Opts (reused)
Edit SS
Document SS
View SS
Window SS
Help SS
The total number of stimulus sets can now easily be determined. The above AAR partial functionality tree contains 18 stimulus sets, of which Main Ops has one repetitive instance. Hence, the number of unique stimulus sets is 17. The requirements encapsulation design rule thus implies that 17 functionality modules should be created to implement the above portion of the AAR functionality tree. Each functionality module encapsulates one stimulus set, where a stimulus set is a highly cohesive collection of requirements (stimulus-response pairs.)
From a design architecture standpoint, the difference between Freedom and current OO is:
a. In Freedom, the CSMs exist to support the FMs. FMs directly satisfy the requirements.
b. In traditional OO, all modules are CSMs because there are no FMs (i.e, requirements are not encapsulated). Thus, the CSMs exist to support one another while simultaneously satisfying the requirements.
The above would seem to imply that CSMs in Freedom are less complex than CSMs in current OO since the burden of directly satisfying the requirements has been removed from them. This is true for some CSMs, but not for all. For example, a printer device driver module or a stack data structure module would be no different in Freedom than is currently the case. Modules that are conceptually closer to the external interface, however, may be significantly different in Freedom than in current practice due to the existence of the functionality modules.
The diagram below depicts the Freedom Canonical Design Architecture.
requirements data and hw
software encapsulation encapsulation
black box Functionality Common Service
interface Modules (FM) Modules (CSM)
\ / / \ / \
=============================================================
|| | | |
external || FM relationship: | CSM relationships: | |
environment || 1. association (NSR) | 1. composition | |
|| | 2. inheritance | computer |
human users || near-tree structure | 3. polymorphism | hardware |
|| (identical to FT) | 4. association | |
external || | | |
system users || | network structure | |
|| | | |
=============================================================
__________________________/\_______________________________________
/ \
Level 0 Level 1 Level 2 Level 3
Main Opts-+-File FM-------------+-Open FM
| NSR +-Save A Copy FM NSR
| +-Document Properties FM-+-Summary FM
| NSR | +-Fonts FM
| NSR +-Document Security FM
| +-Page Set Up FM-----------Paper FM
| +-Print FM-----------------Browse FM
| +-Main Opts (reused)
+-Edit FM
+-Document FM
+-View FM
+-Window FM
+-Help FM
The implications of the requirements encapsulation design rule go beyond merely creating a functionality module for each unique stimulus set. The New Stimulus Set relationship among the stimulus sets must also be honored (after all, it is part of the requirements spec also.) The NSR relationship among the stimulus sets carry over to the functionality modules (FM), and organize the FMs in the same manner as it organizes the stimulus sets. Thus, the requirements architecture of the stimulus sets is precisely mirrored in the design architecture of the requirements encapsulating functionality modules, as illustrated in the bottom half of the Canonical Design Architecture diagram, where the functionality module architecture implementing the sample AAR functionality tree is illustrated.
The architectural symmetry between requirements and design in Freedom makes maintainability easier because maintainers need to learn fewer architectures. Once maintainers learn the architecture of the external interface (information that is needed to properly maintain the interface), they also know the architecture of the implementing design architecture. The benefits work in the other direction as well -- when a developer or maintainer makes a change to the requirements architecture, no additional work is necessary to know the impact on the functionality layer of the design architecture. Thus, the symmetry benefits initial development as well as subsequent maintenance. However, because maintenance cost exceeds development cost by up to 4:1, the primary beneficiaries of Freedom's architectural symmetry are maintainers.
Encapsulating the stimulus-response pairs of a stimulus set involves creating code for:
a. the external interface protocols that exhibit the stimuli;
b. the data and algorithms that implement stimulus detection;
c. the data and algorithms that implement response generation;
d. the external interface protocols that exhibit the responses.
To illustrate the general structure of a functionality module, we will start with the behavior table for the Main Ops stimulus set from post 6. For this example, we will use the behavior table as it appears in post 6 and ignore the fact that the init response would likely not be needed in a fully-specified requirements spec for AAR.
AAR Behavior Table for Main Opts SS
D&I D&I
Stimulus Normal NSR Error Constraint Guidance PAP
-------- -------- -------- -------- ---------- -------- --------
init INPUT
pdf_file
pdf_file_name
pdf_file_content
IF pdf_file_name specified
IF pdf_file is found and valid
display Main Ops
activate Right Display Region SS
activate Left Display Region SS
show pdf_file_content in Right Display Region 1.0 sec max
ENDIF
IF pdf_file not found or invalid
activate File Error SS
display Main Ops
ENDIF
ENDIF
IF pdf_file_name not specified
display Main Ops
ENDIF
-------- -------- -------- -------- ---------- -------- --------
File
activate File SS
-------- -------- -------- -------- ---------- -------- --------
Edit
activate Edit SS
-------- -------- -------- -------- ---------- -------- --------
Document
activate Document SS
-------- -------- -------- -------- ---------- -------- --------
View
activate View SS
-------- -------- -------- -------- ---------- -------- --------
Window
activate Window SS
-------- -------- -------- -------- ---------- -------- --------
Help
activate Help SS
-------- -------- -------- -------- ---------- -------- --------
A functionality module that implements this behavior table as a GUI menu, per AAR, would have the general structure shown below.
// **************************************************************************
// class that encapsulates requirements (stimulus-
// response) pairs for AAR Main Ops behavior table
class MainOps extends Menu {
// ---------------- data declarations for stimulus GUI protocol -------------
private MenuItem file;
private MenuItem edit;
private MenuItem document;
private MenuItem view;
private MenuItem window
private MenuItem help;
// ---------------- data declarations for response behavior support ---------
private [any needed variable declaration];
// ---------------- constructor for MainOps object --------------------------
public MainOps() {
// create menu GUI layout
createMainOpsMenu();
// perform initialization response
initResponse();
}
// end of constructor for MainOps object
// ==========================================================================
// Stimulus Methods
//
// ---------------- method for creating menu GUI layout ---------------------
private createMainOpsMenu() {
// create stimuli for menu GUI protocol
file = new MenuItem ("File");
:
help = new MenuItem ("Help");
// layout the stimuli in a horizontal row
[GUI-specific layout code]
// enable stimuli
[GUI-specific stimulus activation code]
}
// end of method for creating menu GUI layout
// ---------------- method for detecting stimulus events --------------------
public handleEvents(Event event) {
if ([event is from File stimulus]) {
fileResponse();
}
else if ([event is from Edit stimulus]) {
editResponse();
}
else if ([event is from Document stimulus]) {
documentResponse();
}
else if ([event is from View stimulus]) {
viewResponse();
}
else if ([event is from Window stimulus]) {
windowResponse();
}
else if ([event is from Help stimulus]) {
helpResponse();
}
}
// end of method for detecting stimulus events
// ==========================================================================
// Response Methods
//
// ---------------- method that performs init response ----------------------
private initResponse() {
// INPUT
// pdf_file
[implementing code]
// pdf_file_name
[implementing code]
// pdf_file_content
[implementing code]
//
// IF pdf_file_name specified
[implementing code]
// IF pdf_file is found and valid
[implementing code]
// display Main Ops
[implementing code]
// activate Right Display Region SS
[implementing code]
// activate Left Display Region SS
[implementing code]
// show pdf_file_content in Right Display Region
// (must respond in 1.0 sec max)
[implementing code]
// ENDIF
[implementing code]
// IF pdf_file not found or invalid
[implementing code]
// activate File Error SS
[implementing code]
// display Main Ops
[implementing code]
// ENDIF
[implementing code]
// ENDIF
[implementing code]
// IF pdf_file_name not specified
[implementing code]
// display Main Ops
[implementing code]
// ENDIF
[implementing code]
}
// end of method that performs init response
// ---------------- method that performs File response ----------------------
private fileResponse() {
// activate File SS
[implementing code]
}
// end of method that performs File response
// ---------------- method that performs Edit response ----------------------
private editResponse() {
// activate Edit SS
[implementing code]
}
// end of method that performs Edit response
// ---------------- method that performs Document response ------------------
private documentResponse() {
// activate Document SS
[implementing code]
}
// end of method that performs Document response
// ---------------- method that performs View response ----------------------
private viewResponse() {
// activate View SS
[implementing code]
}
// end of method that performs View response
// ---------------- method that performs Window response --------------------
private windowResponse() {
// activate Window SS
[implementing code]
}
// end of method that performs Window response
// ---------------- method that performs Help response ----------------------
private helpResponse() {
// activate Help SS
[implementing code]
}
// end of method that performs Help response
}
// end of class that encapsulates requirements (stimulus-
// response) pairs for AAR Main Ops behavior table
// **************************************************************************
Some observations regarding the above functionality module:
1. The functionality module is implemented as an OO class with the same name as the stimulus set. This makes it easy to identify the class that corresponds to a given stimulus set in the requirements.
2. The constructor creates the protocol manifestation of the stimuli, activates stimulus event detection, and calls a method that performs the initialization response, if any, specified by the behavior table.
In effect, the constructor is the primary vehicle for encapsulating implementation details of stimulus creation and activation for the stimulus set, although it will usually rely on common service methods to carry out most of the lower-level work. The constructor also calls a method that encapsulates any required initialization response.
3. A separate method is created to encapsulate the BT-specified response behavior for each stimulus.
The stimulus behavior-encapsulation methods are the primary vehicle for encapsulating response behavior. Therefore, these methods are declared private or otherwise visibility-restricted just as field data declarations are visibility-restricted when encapsulating data structures in objects.
4. As an aid to implementation of the required response behavior, the structured English or PDL from the behavior table is copied verbatim into the response behavior encapsulation methods as comments when the methods are declared.
In the above example, all BT clauses are binding requirements (i.e., external behavior) and so are not further annotated. Were any of the clauses D&I Constraints and/or D&I Guidance, the comments would be annotated to indicate this fact, such as by placing the term (Guidance) or (Constraint) at the end of the clause.
5. The code that implements each clause of the response behavior is placed immediately below its authorizing comment from the behavior table.
6. Developers should understand the difference between external (required) and internal (Constraint and Guidance) behavior clauses, and implement code for each according to the following guidelines.
Behavior-specific code that implements external behavior (requirements) will appear in its entirety in the functionality module, with the main logic below the authorizing BT clause comments. This is consistent with the concept that a functionality module encapsulates the implementation of its associated requirements. Parts of the response may be delegated to internal methods of the FM consistent with good modular design of a class. Of course, common service modules are used to provide general, i.e., non-behavior-specific, services.
Behavior-specific code that implements internal behavior (Constraints and Guidance) will appear below their respective BT clause comments in the form of method calls to common services modules. This is consistent with the concept that internal details, including internal response aspects of the total responses to external stimuli, are the domain of common service modules. An example of common service module code that implements internal response behavior of a stimulus might be a method that encapsulates "business logic" that has no direct externally visible effect, such as accessing an internal data cache.
The above guideline regarding segregation of internal behavior-specific code between functionality and common service modules should be adhered to unless the Quality Requirements indicate another mapping of the internal behavior to code modules results in improved quality. In all cases, however, external behavior-specific code should be located in the functionality module itself.