DESIGN AND STYLE REVIEW

1. DESIGN

The middle three phases of the waterfall software life cycle model collectively describes the software development stage (see below). The first phase in software development is design.

Design may be described as:

".. the process of applying various techniques and principles for the purpose of defining a device, a process or a system in sufficient detail to permit its physical realisation"

In our case we use techniques and principles such as:

• Top down analysis
• Data tables
• Nassi-Shneiderman charts
• Flow charts

The thing we wish to design is a computer software, and its eventual physical realisation will be in the form of a program written in a programming language (e.g. Ada).

An alternative view of design is to consider the process to be a modelling process whereby a model of the final realisation is produced.

Whatever the case the design process combines:

1. Intuition and judgment based on previous experience.
2. A set of principles and/or "rules of thumb" (heuristics) to act a guidance.
3. A set of criteria whereby quality can be judged - requirements.
4. A process of iteration.

2. NASSI-SHNEIDERMAN

Many design techniques/tools are based on graphical representations ("a picture tells a thousand words"). More precisely many design tools use box diagrams. As the name suggests box diagrams use shapes such as rectangles or squares to represent components in a design. One such tool is the Nassi-Shneiderman chart. The charts were first proposed by Nassi and Shneiderman in the early 1970s and later extended by others.

A reminder of the graphical representation of the control constructs using N-S charts is given below. Note the following:

1. To represent sequence, two boxes are connected bottom to top.
2. To represent an "if-then-else" , a conditional box is followed by a "then part" and an "else part" box.
3. Repetition is depicted with a bounding pattern that encloses the process ("do-while part" or "repeat-until part") to be repeated.
4. Selection is shown by a "case-condition" box followed by a set of "selection" boxes each associated with an "action" box.
5. A procedure or function (routine) name within an ellipse (within a box) is used to indicate a reference call to the named procedure/function.

3. FLOW CHARTS

The flow chart is the most widely used graphical representation for procedural design. The main advantage is that it clearly shows the flow of control (i.e. the "paths") through a software systems. The constructs used to produce flow charts are as follows:

4. DESIGN GUIDANCE RULES

1. Your design should reflect the top down decomposition of the problem to be addressed. Specifically:
   • The main part of the program should have NO implementation details (except in very small applications).
   • The design should be completely broken down into procedures and functions. High level procedures invoke low level procedures. Low level procedures perform a single task. Be suspicious of incomplete decomposition if procedures require more than 15-20 lines of code to implement.
2. Designs should NOT include duplicate code. Code that is similar to code in another place must be combined so the code is written only once, in a procedure or function. Use parameters to accommodate differences in similar code segments.
3. Follow principles of structured programming. One entry - one exit control structures. Enter at the top, exit at the bottom. Wherever possible refrain from using "exit" statements.
4. Avoid using global variables. Each procedure and function should only use local variables or passed parameters if at all possible.
5. Use appropriate features of the language where applicable. For example, use CASE instead of multiple IF's.
6. It is usually bad style to assign the result of a Boolean function to a Boolean variable, or compare the result of a Boolean function to a Boolean constant.

5. STYLE REVIEW

5.1. Indentation

1. Use consistent indenting and alignment of nested control structures. In general, indent any statement that is part of another statement.
2. Use blank lines to separate logical groups of code.
3. Similarly, a line of dashes before a PROCEDURE helps identify/separate the procedure code.

5.2. Comments

1. All comments should be clear, grammatically correct, and use simple English phrases.
2. Prologue: Each program (or package) should include a prologue block or "header." The header includes at least program name, author and date, and may include some description and/or version history.
3. Each procedure and function should be introduced with a short description.
4. Generally each control structure block (loop, selection, case, sequence block) should include some annotation, in the form of a comment.

5.3. Naming conventions

1. Ensure that identifiers have meaningful names, i.e., names that convey as much information as possible about what the object is or what the process does. For example TOTAL_PERSONS is better than COUNT, and ROW is better than I.
2. Choose names for different identifiers that are "psychologically distant" in order to avoid confusion.
3. Consider using nouns for types, constants, variables, and verb phrases for procedures and functions.
4. Use enumerated types to represent non-alphanumeric data. NEVER use INTEGERS to 'encode' non-integer data items.

5.4. Constants

Use constant identifiers in your program instead of "magic numbers." For example for LOOP_PARAMETER in 1..200 is not acceptable. What is 200?

5.5. Declaration order

Consider adopting some consistent declaration order. For example:

1. Named numbers (constants, to avoid magic numbers)
2. Types and subtypes
3. Named constants
4. Instantiated Packages
5. Variables

Created and maintained by Frans Coenen. Last updated 11 October 1999