NOTICE

Touch Technologies, Inc. (TTI) has prepared this publication for use by TTI personnel, licensees, and customers. This information is protected by copyright. No part of this document may be photocopied, reproduced or translated to another language without prior written consent of Touch Technologies, Incorporated.

TTI believes the information described in this publication is accurate and reliable; much care has been taken in its preparation. However, no responsibility, financial or otherwise, is accepted for any consequences arising out of the use of this material.

The information contained herein is subject to change without notice and should not be construed as a commitment by Touch Technologies, Inc.

Revised: March 23, 2005

Copyright ©2004 - 2005 Touch Technologies, Inc.

Contents

Index

About this Manual

This document describes the programming, testing and other procedural standards used by Touch Technologies, Inc (TTI). The document serves to present the standards used by TTI's programmers. The standards as outlined here are used by all TTI programmers when writing and revising code.

Purpose of Standards

These standards have been developed in order to facilitate the writing and maintaining of code. Use of the standards in this manual will provide the following:

• Readable and understandable code by encouraging the use of an outline structure and easy string searches.
  
• An easy way to distinguish new code from code done by other groups or companies to simplify code review and debugging when doing conversion projects.
  
• A simple, usable directory structure for retaining code to make review and maintenance easier.
  
• Specific facilities and procedures to rebuild code for ease of maintenance.

Intended Audience

This manual is written for experienced programmers who write new programs and modify existing code.

SheerPower Reference Manuals

All SheerPower manuals are designed to provide information in a manner that is concise and easy to use. The manuals are:

• A Guide to the SheerPower 4GL Language
• SheerPower Coding Standards

Overview

This chapter describes the standards for implementing new code. The standards described in this chapter apply to any new programs written and to ANY and ALL modifications made to existing code.

The goal of implementing these standards is to make the code more maintainable by:

• Making code easy to add, modify and read.
• Making debug code easy to find and remove.
• Making it easy to find and change variables, routines, etc.

The standards make it easier to conduct and supervise programming projects by providing set procedures and coding standards. The structure of the code allows the programmer to easily find pertinent parts of code, and to ignore irrelevant items.

The standards encourage an outline format for programs. The outline format looks something like this:

Example 1-1 Program Outline Format

Program Definitions | Initialization | Main Logic | First Routine | Other Major Routines | Minor Routines

The standards in this manual do not dictate that minor routines must fall after major routines. However, they do require that all subroutines appear after the routine which calls them.

If the programmer prefers to put subroutines closer to the routines which call them, the following format could be used:

Example 1-2 Optional Program Format Outline

Program Definitions | Initialization | Main Logic | First Routine Subroutines from first routine | Major Routine Subroutines from major routine | Major Routine Subroutines from major routine . . .

With either format, the object is to provide code which is easy to read and easy to modify. These goals are furthered by the requirement that all routines be 25 lines or fewer in length. 25 lines is the number of lines which can be viewed at one time on most laptop monitors.

Small routines encourage the programmer to keep routines simple. A small routine simply cannot do too much. Because of that, it must be very concise and can serve only a specific function. When a programmer is debugging or modifying a program, it easy to see what the routine is doing--because it is only doing 25 lines of material.

Since the routines are so specific, it is easy to decide whether a given routine or any of its subroutines could be creating the bug. In this way, the programmer can scan through the program from top to bottom and quickly pinpoint the area where the bug is occurring.

The standards require that routines be written in the same format. This helps make the code cohesive. It also means that when a team of programmers is working together, or when a new programmer takes over for a departing programmer, everyone knows what to expect. Everything has the same format so there won't be any surprises. New programmers will not have to spend large amounts of time learning the quirks and styles of other individuals.

The formats for the programs and routines are designed to highlight important points and make them more visible. This again makes it easier for the programmer to spot important differences between routines. Headers are highly visible so the programmer doesn't have to search for where the code begins and ends within the routine.

The goal of imposing standards with regard to programs and routines is to make them uniform, readable and understandable. Uniform standards make it easier to read routines and to locate information. The standards are designed to highlight important information and sections in the code.

Each program begins with a program header. The first line of the program is a comment line of percent signs:

!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The percent line should consist of an exclamation mark followed by 65 percent signs.^* The next few lines are comments containing information about the program. The following topics should be included:

Program --- the program name
System --- the package or system the program is a part of (if any)
Author --- the programmer's name
Date --- the date the program was created
Purpose --- a description of the purpose of the program

All the topics should be preceded by the topic title and indented evenly. The program header should end with another percent line. Below is an example of a correctly formatted program header:

Example 1-3 Program Header Format

!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ! Program: NODEF ! System : IBIS ! Author : John Matthew ! Date : January 7, 2003 ! Purpose: Remove function definitions from ! a basic source file and insert ! include statements !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

* Examples in this manual may have fewer than 65 percent signs because of margin considerations.

Below is an example of a correctly formatted Initialization Area:

Example 1-4 Initialization Area

!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ! I n i t i a l i z a t i o n !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% sh_file$ = "c:\sheerpower\spproject\data.html" round_amount = .005 . . .

This is where you declare variables or dimension arrays--filling them with initial values. For example, if the year 1955 was used as a SPECIAL YEAR throughout the program:

special_year = 1955

would be placed in the Initialization section of the program template.

Below is an example of a correctly formatted Main Logic Area:

Example 1-5 Main Logic Area

!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ! M a i n L o g i c A r e a !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% check_files . . . stop

The Main Logic Area contains all of the code that is not initialization code and is not in a routine.

See Section 5.1, GOLD/P Program Template for instructions on how to automatically create a professional program template using a specially mapped keystroke in SPDEV.

All routines have the same format and are placed under a Routines heading. The format for a routine is:

Example 1-6 Routine Format

!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ! R o u t i n e s !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ! r o u t i n e _ n a m e !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ! ! Brief description: ! description of routine ! ! Expected: ! variables that need to be set for this routine to ! execute ! ! Locals: ! local variables used in routine ! ! Results: ! result of routine, and variables set up in this ! routine ! !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% routine routine_name --- --- body of routine --- end routine

The object of having standards for the format of routines is to make the routines easier to find, follow and maintain. Strict standards are enforced. They ensure that the same format is used, regardless of which programmer wrote the routine. They also ensure that the pertinent information is provided with each routine. Each routine will consist of the following:

• the routine header
• the ROUTINE name statement
• the body of the routine
• the END ROUTINE statement

Below is an example of a correctly formatted routine header and routine:

Example 1-7 Correctly Formatted Routine

!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ! p r i n t _ g r a n d _ t o t a l s !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ! ! Brief description: ! This routine display the totals for the sales ! report. ! ! Expected: ! t_parts = total number of parts sold ! t_sales = total sales in dollars and cents ! aup = average unit price: t_sales/t_parts ! ! Locals: ! ! Results: ! tot_printed = true ! !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% routine print_grand_totals print #report_ch print #report_ch: tab(50); "Total parts: "; t_parts print #report_ch: tab(50); "Total sales: "; t_sales print #report_ch: tab(50); "Average unit price: "; aup let tot_printed = true end routine