Footnotes

INTRODUCTION

1. Or equivalent self-study, which is very rarely accomplished in reality despite honest intentions.

1 SOFTWARE DEVELOPMENT METAPHORS

1. Probably the only time this consideration comes up in software development is when the program becomes so large that it requires multiple CDs, DVDs, or other media for distribution.

2. Arguably, we could say software “wears out” when the hardware it requires becomes obsolete and eventually fails without any way of being replaced.

3. We’ll ignore the cost of development, marketing, and upgrade fees here, and simply consider the cost of doing a field upgrade of a piece of software.

4. Kathleen Melymuka, “Why Musicians May Make the Best Tech Workers,” CNN.com, July 31, 1998.

5. An exception might be a performance artwork, such as a fireworks display.

6. That is, two software systems with the same approximate complexity could vary by a factor of almost 100 in terms of the number of lines of code.

7. Another advantage to the apprenticeship process is that multiple individuals now understand how the code operates, so if one leaves, another can pick up the project in their place.

8. For those too young to remember VisiCalc, it was the precursor to Microsoft Excel.

2 PRODUCTIVITY

1. Harold Sackman, W. J. Erikson, and E. E. Grant, “Exploratory Experimental Studies Comparing Online and Offline Programming Performance,” Communications of the ACM 11, no. 1 (1968): 3–11.

2. Barry W. Boehm, Terence E. Gray, and Thomas Seewaldt, “Prototyping Versus Specifying: A Multiproject Experience,” IEEE Transactions on Software Engineering 10, no. 3 (1984): 290–303.

3. Generally, this means larger, although conceptual complexity applies as well.

4. Some large projects appoint a “librarian” whose job is to keep track of reusable code components. Programmers looking for a particular routine can ask the librarian about its availability and spare themselves from having to write that code. The productivity loss is limited to the time the librarian spends to maintain the library and the time the programmer and the librarian spend communicating.

5. Note that a project might contain multiple executable files. In such a case, the “executable file size” is the sum of all the executable components in the system.

6. Assuming, of course, that the library routines existed prior to the project and were not part of the project’s development.

7. True function point analysis is based on five components: external inputs, external outputs, external inquiries, internal logical file operations, and external file interfaces. But this basically boils down to tracking the inputs, outputs, and computations.

8. Claude E. Walston and Charles P. Felix, “A Method of Programming Measurement and Estimation,” IBM Systems Journal 16, no. 1 (1977): 54–73.

9. Today, I don’t have a problem recommending Swift. It’s a great language, and version 5.0 and later seem relatively stable and reliable. It’s moved beyond the “Gee whiz, ain’t this a great new language” stage and is now a valid software development tool for real projects.

3 SOFTWARE DEVELOPMENT MODELS

1. Depending on the system, they might also produce a Hardware Requirements Specification (HRS) document, and other documents as well, all of which are outside the scope of this book.

2. The original definition of hacking, from https://www.merriam-webster.com, is “a person who is inexperienced or unskilled at a particular activity; e.g., a tennis hacker.”

3. Of course, along the way the term hacker was also redefined to describe someone engaged in criminal activities on computers. We’ll ignore that definition here.

4. I was once tasked with setting up user interface colors on an embedded application. The client requested one set of colors. A week later I showed up with their desired changes, and they didn’t like them. So, we tried a second set. They didn’t like those. Then a third set, then a fourth set. A month later they decided the initial color set was the best. In the meantime, the project had lost a month.

5. Sadly, the link to this quote is no longer active. Ah, the joys of the internet. Nevertheless, this is one of the best, most concise definitions I’ve found that doesn’t try to promote a particular methodology.

6. Note that although face-to-face communication is more efficient, these meetings can also have a negative impact on engineers’ productivity. See “Focus and Eliminate Distractions” on page 34 for more details.

7. They’re called “stand-up” meetings because everyone who can is required to stand up. This makes everyone physically uncomfortable, which results in shorter meetings.

8. Wilfrid Hutagalung, “Extreme Programming,” http://www.umsl.edu/~sauterv/analysis/f06Papers/Hutagalung/.

9. Actually, there are 28 different XP rules, but they can be simplified to these 12.

10. http://en.wikipedia.org/wiki/Pair_programming

11. http://collaboration.csc.ncsu.edu/laurie/Papers/dissertation.pdf and https://collaboration.csc.ncsu.edu/laurie/Papers/ieeeSoftware.PDF

12. This isn’t quite the same as having a manager constantly looking over your shoulder because your team isn’t explicitly watching what you’re doing. Hence, the stress level is quite a bit lower.

4 AN INTRODUCTION TO UML AND USE CASES

1. This is a good example of redundancy in UML—that is, using two different notations for the same thing.

2. This is a nonexhaustive list. You may freely add any items specific to your project.

3. This example is from a real-world project: Plantation Productions’ “Open Source/Open Hardware Digital Data Acquisition & Control System” (http://www.plantation-productions.com/Electronics/DAQ/DAQ.html).

5 UML ACTIVITY DIAGRAMS

1. Some authors use roundangles, rectangles with rounded corners, to show activities. However, the UML standard uses roundangles for states.

2. For the most part, an event and a trigger in UML are the same thing—a signal from a source outside the current flow of control that causes a change in it. This book uses the terms trigger and event interchangeably.

3. Note that UML’s thread operations are only a suggestion. When a UML diagram shows multiple threads executing concurrently, it’s simply an indication that the separate paths are independent and could be executed concurrently. In actual execution, the system could execute the paths serially in any order.

4. Older versions of UML call partitions swim lanes, so you’ll see that term used in many books and papers referring to this construct.

6 UML CLASS DIAGRAMS

1. The standard convention in C-derived languages is to use all uppercase characters to denote constants, but this is an absolutely terrible convention that I refuse to use for my own constants because ALL UPPERCASE IDENTIFIERS ARE MUCH HARDER TO READ THAN MIXED-CASE IDENTIFIERS. I modified the Unix convention of using _t to specify a type identifier to include _c for constants. Also, this convention is applicable across multiple languages and is not specific to C++.

2. This is not to imply that you should never make a variable attribute public. As with any other convention or rule, there are always exceptions where it makes sense to violate the convention. However, violations should be rare.

3. Some modern languages, like Apple’s Swift, provide syntax options that let you invoke getter and setter functions using standard assignment operations. Therefore, there’s no syntactical overhead associated with using getters and setters (other than, of course, writing the getter or setter methods in the first place).

4. Package and protected visibility might vary in this diagram depending on your choice of programming language, but the basic idea of a spectrum applies nonetheless.

5. Case neutrality guarantees that the names you choose will be valid in both case-sensitive and case-insensitive languages. For example, hello and Hello would be considered different names in a case-sensitive language like C++, but the same in a case-insensitive language like Pascal. Neither is case neutral, so you should consistently use only one or the other in UML diagrams.

6. Underlining the attribute is the standard way to specify static objects in UML, but using a property string is probably clearer.

7. Similar to a key but not identical. A database maintains records and keys as disk files; qualifiers generally assume an in-memory data structure, such as an associative array, hash table, or map, to provide access to the specific record of interest.

8. The base class is also known as the ancestor class.

7 UML INTERACTION DIAGRAMS

1. If you’re thinking this is a bad design element in the UML language, you’re correct. Given its history and design-by-(political)-committee approach, it’s understandable why UML isn’t a little cleaner.

2. Indeterminate upon encountering the beginning of the loop on the first iteration.

3. Arguably, an infinite loop with a break sequence fragment is also an indefinite loop, not an infinite loop.

4. There will be two or more, separated by dashed lines, similar in syntax to the alt sequence fragment.

8 MISCELLANEOUS UML DIAGRAMS

1. The protected, private, and package visibility prefixes are also valid here with the appropriate meanings.

2. Technically, we should put a transition arrow from a state back to that same state labeled else to handle this situation; however, the else condition is implied in UML statechart diagrams.

9 SYSTEM DOCUMENTATION

1. Hardware requirements might be extracted to a Hardware Requirements Specification (HRS), and other requirement types might be likewise extracted to their own specialized documents. Those documents are beyond the scope of this book.

2. While the STC can be influenced by the SDD, it’s generated from the SRS, because you create test cases from the requirements, not from the design. Any test cases constructed from the SDD will come from design entities originating from requirements.

3. Keep in mind that the SyRS might contain hardware and other non-software-related requirements that wouldn’t be copied to the SRS; for more information, see “The Requirements/Reverse Traceability Matrix” on page 178, particularly the description of allocations.

4. In well-designed systems, there can be a many-to-one relationship between requirements and design items; in the worst case, there is a many-to-many relationship.

5. Generally, if you need to test something, a requirement should be driving that test. However, you might derive some test cases from the SDD rather than directly from the SRS. For example, the requirements generally don’t state details such as whether a coder should use an array or a dictionary (lookup table) to implement some operation. The SDD, on the other hand, might specify a particular data structure such as an array. This could lead to a test case that tests to ensure the program doesn’t violate the bounds of the array when indexing into it.

6. It might turn out that a single test case would incidentally work for multiple requirements. However, you would still produce independent test cases. This redundancy is resolved when you create the test procedures.

10 REQUIREMENTS DOCUMENTATION

1. Arguably, this could be rewritten as the single requirement “The pool monitor shall clear the ‘good’ condition when the temperature is outside the range 70 to 85 degrees F.”

2. For information on the Plantation Productions DAQ system, see http://www.plantation-productions.com/Electronics/DAQ/DAQ.html.

3. TRIGA™ is a registered trademark of General Atomics, Inc.

4. The Netburner runs a priority-based multitasking operating system called Micro-C/OS (or μC/OS). Tasks are the equivalent of threads in other operating systems.

5. For example, some requirements might state that it is preferable to damage the system hardware rather than allow the system to enter a state that might cause bodily harm or death. You would not want to test this by damaging the system.

6. This is my opinion, so feel free to add or remove items from this list if your opinion differs. Note that I will use this list when creating a Software Review List later in this book.

11 SOFTWARE DESIGN DESCRIPTION DOCUMENTATION

1. IEEE Std 1016 is a registered trademark of the IEEE. IEEE Std 1016-2009 is a revision of IEEE Std 1016-1998 that incorporates UML as the software modeling language.

2. There are actually 29 use cases in the full use case diagram. See http://www.plantation-productions.com/Electronics/DAQ/DAQ.html.

3. The IEEE Std 1016-2009 includes many older viewpoints carried over from the 1016-1998 standard. You probably shouldn’t use these older viewpoints in new designs. They are included only so that older SDD documents can still claim to be compliant with IEEE Std 1016.

4. In almost every sample SDD I’ve found on the internet, the authors combine design viewpoints and design views into the same sections. When they differentiate them, the Design Views section is a brief introduction and the actual views are listed under the Viewpoint sections (which seems backward to me, but the IEEE Std 1016-2009 document is not very clear on this matter).

5. With a few changes for clarity.

6. Note that a many-to-many relationship between design concerns and components in a design view isn’t invalid, even if you attach tags to all of the components. However, the RTM can become unwieldy when this happens and, seeing as the RTM is messy enough as it is, you don’t want to make it worse.

7. These modifications are for clarity and consistency with the SRS guidelines (see “The System Requirements Specification Document” on page 193).

8. The index is actually empty for editorial/space reasons. It is a placeholder in this sample to show that you should provide an index in your SDD.

9. The requirements listing also provides a means for evaluating/verifying the design to see that it meets the specifications defined in the SRS. A reviewer will compare each of the listed requirements in the SRS against the contextual view to see that the view meets the requirements.

10. As the contextual view is provided here, there’s no need to discuss the analysis needed to create the design view; that’s trivial, because the design view is already present.

11. At least those components important to this SDD.

12 SOFTWARE TEST DOCUMENTATION

1. IEEE Std 829-2008 is a registered trademark of the IEEE.

2. It might seem strange to not have any test cases at all. However, keep in mind that having too many trivial test cases will make the testing process lengthy and more expensive, resulting in too little time spent testing the really important features of the system.

3. The names in parentheses are not part of the IEEE Std 829-2008. However, they are common industry names.

4. The parenthetical names are common names for these test plans; these names do not come from Std 829.

5. A good example of such an external organization is the Nuclear Regulatory Commission (NRC), a US-based governmental organization tasked with licensing commercial nuclear reactors.

6. I personally prefer this approach, even at the cost of maintaining duplicate information (and potentially introducing inconsistencies), because it keeps those documents self-contained (especially the test procedure documents). During the testing process, I don’t want to have to keep referring to different documents, which can slow down the testing and lead to errors in the testing process.

7. There are other verification types, but we’ll ignore those here. If you ever use those types (typically for hardware, although analysis, other, and no test are possible software options), you’ll have to create an appropriate document that justifies or describes how you will verify the associated requirement.

8. As usual, I’ve included some common (non-IEEE) names in parentheses.

9. Do keep in mind, however, that creating the automated test procedure can be expensive and you have to validate the resulting code to ensure that it properly executes all the tests. In the long run, automated test procedures tend to be cost-effective because on all but the smallest of projects, you wind up rerunning test procedures many times during development.

10. Even if your system is not life-threatening or doesn’t exhibit catastrophic consequences if it misbehaves, having formal SITC and ATC documentation can help prevent you from delivering a shoddy product. At the very least, great code is going to run through a formal test process with formal test case/test procedure documentation.

11. Note that test runs must be reproducible outputs. Therefore, random input data is rarely appropriate as an input data stream unless you’re testing average responses to inputs that don’t depend on any particular input data set.

12. Write Great Code, Volume 6, will go into details concerning code scaffolding and drivers.

13. Once you’ve seen a half-dozen sample test cases or so, you’ll learn the basic idea of how to write them. Explicitly providing all the test cases for a phantom project like the DAQ DIP switches won’t help you learn the material any better.

14. Commercial off-the-shelf systems.

15. As usual, I’ve included some industry-standard names that are synonyms for the Level Test Procedure names in parentheses. Remember, Software Test Procedure is a generic term representing any one of these four levels of test procedure.

16. This is not always true. Sometimes the SATP has to include additional testing procedures to deal with site environmental issues that may not exist at the factory. For example, noise (electrical as well as acoustical) and the actual physical system installation may expose some defects that could not be caught on the factory floor.

17. It’s also missing the Context field, but that’s nearly irrelevant here. The context is implied by the Context field in the STC documentation.

18. Indeed, QA guidelines claim that it is unacceptable and unethical for developers to run the formal system integration and acceptance tests for a product. Many companies won’t even allow the developers to produce the executable code, instead relying on the QA department to construct the builds from the source code control system for testing.

19. Some might even require running the entire STP from the beginning, although this is usually too expensive and, therefore, impractical. The usual compromise is to rerun each test procedure that fails and then, at the end of the STP, rerun the whole STP to guarantee it runs in its entirety without failure.

20. As noted earlier, some QA teams will require running the entire LTP over again if there were any failures on individual test procedures (whose defects were presumably corrected and retested). This ensures that all test procedures in the LTP all have the same version number.

21. As usual, I’ve included some common names (non–Std 829) in parentheses.

22. You should, of course, update the electronic version of the document so you don’t have to re-redline the test procedure if you ever have to run it again.

23. Personally, I would have a big problem with this approach. However, if you have a particularly large test procedure, it could be very expensive to restart that procedure every time testers find a defect.

24. Many defect-tracking systems are accessible via a web page interface. So as long as you have internet access and your tracking system is available online, you can fill out bug reports remotely.

25. With careful requirements design, you can probably eliminate the SRL if all your requirements are testable. If you are really brave, you could combine the STC and LTP into a single document; however, it’s almost always a better idea to keep them separate.