Program Quality

J. Philip East

A programmer can and should emphasize more than just the correctness of the program. Other aspects of program quality such as user-interface, code-layout, documentation, etc. can positively or negatively affect the use and revision of a program. So, while learning to program you should attend to writing correct programs, but you should also be working to establish and enhance your programming style.

Instructors often suggest students follow their style recommendations. But, there is no universally accepted good style. For the most part I will expect students to adhere to my style recommendations but they may choose to either follow the guidelines listed here or have well-reasoned rationales for not doing so.

Design
clarity Programmers should almost always choose clarity over cleverness and often choose it over efficiency.
use of
modularity 		Programs should be modular—broken into functions, procedures, methods, etc. than can be called from/by other segments of code. Modules should be used when:
  • the same collection of code appears multiple times
  • a collection of statements achieves a separate task from that of surrounding code
  • code is more than one page in length (including documentation)
modular
design 		Good design requires good use of modularity, i.e.,
  • high cohesion— modules perform a single task
  • low coupling— data values communicated through parameters but parameter use is minimized and local data use maximized
adherence to
specifications 		sometimes, specifications for a programming task require you to use specified data structures or algorithms. Do so.

Coding Sytle
language feature
selection 		know your language well enough to choose well when multiple mechanisms exist for accomplishing the task (and choose well when alternatives exist)
code granularity I use the word granularity refer to the level of code you are using. In particular, it seems unreasonable to mix a bunch of native code with module invocations. The module invocations are presumably the most important/critical part of the code but they appear to have the same importance as any other line of code.
code duplication In this context, code duplication refers to having the same code in different parts of a single compound statement (if-then-else, case structure, etc.) Sometimes this is necessary, but usually the code can be removed from within the statement and placed either before of after it.

User Interface
For highly interactive programs, assessment of the user interface can be a complex task. Most of the programs I assign are not highly interactive. They should, however, have several characteristics that I think of as related to user interfaces.
inform
the user 		Let the user know what is going on:
  • what your program does (a brief overview)
  • progress is being made by your application
  • file names for generated reports
report
preparation 		Format reports to be a clear and concise as possible. Some suggestions for doing so are:
  • provide title information (title, date)
  • (perhaps) provide an overview
  • minimize descriptive matter
  • use tables when data is repetitive
  • space columns closely (3-5 spaces)
  • use column headings
  • align column headings, spacers, values, and totals in a reasonable manner
  • use single spacing (in tables)
  • control where lines and pages break

Documentation
The ideal goal is that programs be self-documenting, i.e., that the code clearly indicates what it does. This is seldom possible because we can not know the mindsets of readers. Thus, we resort to natural language (English) documentation. I encourage consideration of three main aspects of documentation and some general concerns.
Program Tell briefly and generally what the program accomplishes. Do not reiterate the algorithm. Include:   program purpose,   program author(s) (and helpers),   external modules used,   all data limitations,   and anything special a user of program should know. If the program is designed as a tool for others to use, describe how the tool can be connected to a host program and how its modules are to be invoked.
Module Indicate briefly what the module accomplishes and list all non-obvious pre- and post-conditions. When the purpose of a module is obvious (and the module is short), documentation may be omitted.
Code Generally, all code should document itself. Some points to remember are:
  • do not explain identifiers—choose better names!
  • do not allow comments to duplicate code
  • explain tricky segments of code
  • consider using comments to separate and identify segments of code within the same module (you have a good reason for having separate segments, right?)
General
Concerns
  • make documentation as brief as possible, but still communicative
  • format code so that documentation and code are easily distinguishable

Code Layout
The principal goal of attending to code layout is to make programs easier to follow when they have to be examined in the future. While our programs may not be examined much in the future, those we write after graduation almost certainly will be. Develop good habits and the ability to adapt to local expectations.
Spacing
  • separate logical "chunks" of code with blank lines
  • use more spacing around "chunks" than within chunks
  • use more spacing around modules than within modules
  • use horizontal/in-line spacing to enhance readability
Indentation
& Alignment
  • use a reasonable amount of indentation (3-5 spaces)
  • be consistent with indentation
  • indent the scope of all statements
  • align markers of scope —   begin & end,   { & },     if & else & end-if,   etc.
  • align the beginning of all statements in the same scope
Line
Continuations
  • break statements that exceed the screen or page width
  • break statements before operands (+, -, *, /)
  • indent continued statements beyond the beginning of the statement
  • align continued statements in some logical manner