Chapter 7
Writing the Programs
CSCI 3428: Software Engineering
Tami Meredith
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
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!)
Programming Guidelines
 Control Structures
 Aim for linearity
 Algorithms
 Execution time vs. {cost, time, understandability, testing,
maintainability, ...}
 Data Structures
 Simplicity, sufficiency, extendability
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
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
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
*/
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
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!
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
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.
 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