What is a Good Program Spec?


Since the industry is preoccupied with producing software faster
(and not necessarily better), let’s stop and consider how we typically approach programming and allow me to put my spin on it. There are fundamentally three aspects to any program development effort: defining the program’s specifications, designing and writing the program itself, and testing it. The software engineering gurus in the industry are primarily concerned with the internal design of the program, but there
is now a raft of consultants trying to determine the best way to
approach the program externally. Why? Because there is now many ways for producing software than just writing source code using a common text editor; e.g., visual programming aids/prototyping tools, workbenches, 4GL’s, program generators, etc. Such tools take the need for writing precise source code out of the hands of the programmers and allows them to concentrate on basic screen and report layout. They are excellent tools for most programming assignments, but they cannot do 100% of all of the programming for all applications. We still require
professional software developers with an intimate knowledge of programming languages and design techniques. Regardless if we write a program by hand, or use some sort of interpreter/generator, we still need to provide the programmer with precise specifications in order to perform their work.

Seldom do companies make use of a uniform approach for producing program specifications. It is not uncommon for programmers to receive specs in obscure ways, such as a memo from an end-user (the back of a cocktail napkin is my personal favorite). Rarely are specifications given in a consistent manner that can be evaluated for completeness. A standard approach would improve productivity and communications within the programming staff alone.

What should a good program spec include? Actually, its not too
difficult to figure out…


Each program should be defined in terms of:

  1. Input Descriptions (to collect data or request an output) – be it implemented by a GUI, command line interface, verbal, optical, or through some other screen interface. All inputs should include: a. Name, alternate ID, program label, description. b. Defined layout and examples. c. Input transaction specifications, including default values and editing rules for data to be collected. d. Messages; e.g., data validation, and general processing. e. Panels (for screens). f. Relationship of inputs to outputs.
  2. Output Descriptions (to retrieve data) – be it implemented by a GUI, printed report, audio/video, or through some other screen interface. All outputs should include: a. Name, alternate ID, program label, description. b. Defined layout and examples. c. Panels (for screens), maps (for reports). d. Messages; e.g., general processing and program specific information/warning/error messages.
  3. Data Structure Descriptions (data bases, files, records, and data elements). NOTE: Programmers should NOT be in the business of designing data bases as they will only do what is convenient for their application, not others (thereby missing the opportunity for a company to share and re-use data). Physical files should be defined by Data Base Administrators. a. All data structures should include: Name, alternate ID, program label, description. They should also include… b. Data Bases – organization, key(s), labels, volume/size, backup requirements, internal structure. c. Files (both primary and working) – organization, key(s), labels, volume/size, backup requirements, internal structure, file-to-file relationships. d. Records – form, length, key(s), contents, record-to-record relationships. e. Data Elements – class, justification, fill character, void state, mode, picture, label, size, precision, scale, validation rules. If generated data, rules for calculation. If group data, rules for assignment.
  4. Program Description: a. Name, alternate ID, program label, description. b. Characteristics: Required processing speed, memory requirements. c. Dependencies to other programs externally (e.g., batch job stream). d. Dependencies to modules internally (e.g., DLLs, subroutines, etc.) e. Functions to be performed with Inputs, Outputs, and Data Structures (create/update/reference). f. Special processing rules (logic for processing) g. Command language required to execute the program (e.g., command files, JCL, etc.) h. Physical environment where program will be executed. i. Test Plan and how to assemble test data. j. Method of implementation – programming language(s) to be used, design techniques to be observed, tools to be used.

Leave a Reply

Your email address will not be published. Required fields are marked *


Malicious Programs

Similar to motorists who travel at 10 miles per hour below the posted speed limit in the left-hand lane, programmers who deliberately create and distribute malicious computer programs don’t have a clue. They have a great deal of knowledge and expertise but they can’t seem to figure out how to function by simply following the […]