1. CSCI 3428: Software Engineering Tami Meredith Chapter 7 Writing the Programs

2. Standards A prescribed set of rules for esthetic, syntactic, and semantic choices in order to create uniformity Examples: Location of parentheses Variable naming convention i++; vs. i += 1; Blank lines, comments, etc. When to use Macros vs. Functions vs. Inlining Generally specific to a company/culture E.g.: http://www.gnu.org/prep/standards/standards.html

3. Why? Help others understand your code Improves readability Reduces time/costs Assists in error detection during reviews Assist in automatic translations Improves portability Reduce decision making when coding Can help organise your thinking Esthetics easily managed using a pretty printer such as gnu indent (low overhead!)

4. Programming Guidelines Control Structures Aim for linearity Algorithms Execution time vs. {cost, time, understandability, testing, maintainability,...} Data Structures Simplicity, sufficiency, extendability

5. Good Practice Localisation of input and output Localisation of variable definitions Including pseudocode Revise and rewrite – NOT patching Maximise reuse Write once, debug once Reduce code size and reduce bug count Reasonable subtype depth Avoid over-commenting Unnecessary "efficiency" – clarity should come first http://www.kmoser.com/articles/Good_Programming_Practices.php

6. Documentation: Internal Header comment block Comments are "value added" Meaningful variable, function, and label names Formatting to improve understanding Symbolic constants Data maps to describe data structures Stuff to make reading/understanding the code easier

7. Bad Comments Obscure readability Are out of date or wrong screen space and make blocks harder to see Hide or obscure code int /* function */ main (argc, argv) /* mainline for application requires */ int argc; /* count of arguments as number */ char **argv; /* array of arguments as ints and returns an integer that is the exit value */

8. Function Header Blocks Name, Author, Date Revision History Purpose Notes on operation Expected I/O Logic, flow, error-handling Testing notes Expected extensions or revisions

9. Documentation: External Specifications, Requirements Programming Rationales Problem Assumptions, Constraints, Limitations Algorithms Data Structures Links to Specifications QUIRKS! Stuff people won't know from reading the code!

10. Things that can help... Identifying related problems Restating (explaining) the problem Decomposing the problem Exploring assumptions "Thinking out of the box" Programming the "wrong" thing

11. Fry Me! Famous Moments in Software Engineering AECL Therac 25 (1985) AECL did not have the software code independently reviewed. AECL did not consider the design of the software during its assessment of how the machine might produce the desired results and what failure modes existed. The system noticed that something was wrong and halted the X-ray beam, but merely displayed the word "MALFUNCTION" followed by a number from 1 to 64. The user manual did not explain or even address the error codes, so the operator pressed the P key to override the warning and proceed anyway. AECL personnel, as well as machine operators, initially did not believe complaints. This was likely due to overconfidence. AECL had never tested the Therac-25 with the combination of software and hardware until it was assembled at the hospital.

12. The failure only occurred when a particular nonstandard sequence of keystrokes was entered on the VT-100 terminal which controlled the PDP-11 computer: an "X" to (erroneously) select 25MV photon mode followed by "cursor up", "E" to (correctly) select 25 MeV Electron mode, then "Enter", all within 8 seconds.This sequence of keystrokes was improbable, and so the problem did not occur very often and went unnoticed for a long time. The design did not have any hardware interlocks to prevent the electron-beam from operating in its high-energy mode without the target in place. The engineer had reused software from older models. These models had hardware interlocks that masked their software defects. Those hardware safeties had no way of reporting that they had been triggered, so there was no indication of the existence of faulty software commands. The hardware provided no way for the software to verify that sensors were working correctly (i.e., an open-loop controller). The table-position system was the first implicated in Therac-25's failures; the manufacturer revised it with redundant switches to cross-check their operation. The equipment control task did not properly synchronize with the operator interface task, so that race conditions occurred if the operator changed the setup too quickly. This was missed during testing, since it took some practice before operators were able to work quickly enough to trigger this failure mode. The software set a flag variable by incrementing it. Occasionally an arithmetic overflow occurred, causing the software to bypass safety checks