Touch Technologies, Inc. Coding Standards

Touch Technologies, Inc.
Coding Standards

Touch Technologies, Inc.
10650 Scripps Ranch Blvd., Suite 100
San Diego, CA 92131

1-800-525-2527 or 1-858-566-3603
SheerPower@ttinet.com

Note

tm SheerPower is a registered trademark of Touch Technologies, Inc.

® VMS is a registered trademark of Digital Equipment Corporation.


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


Preface

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:

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:


Chapter 1
Coding Standards for New Code

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:

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.

1.1 Format of Programs and Routines

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.

1.1.1 Program Header

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.

1.1.2 Initialization Format

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.

1.1.3 Main Logic Area Format

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.

1.1.4 Routine Format

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:

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 


Next Contents Index