Touch Technologies, Inc.
Coding Standards

Each routine begins with a header. The header is bordered by two lines of percent signs and contains the routine name and any necessary descriptions. The routine name must be unique and contain at least one underscore "_".

Below is an example of a sample routine header:

Example 1-8 Sample Routine Header

(1)!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% (2)! p r i n t _ g r a n d _ t o t a l s (3)!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ! (4)! Brief description: ! This routine displays the totals for the sales ! report. ! (5)! Expected: ! t_parts = total number of parts sold ! t_sales = total sales in dollars and cents ! aup = average unit price: t_sales/t_parts ! (6)! Locals: ! (7)! Results: ! tot_printed = true ! !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

1. Beginning percent line. The header begins with a comment line containing 65 percent signs.^*
2. Routine name. The routine name should be double-spaced and in lower case. There should be one space between each letter and underscore.
3. Second percent line, followed by a blank comment line.
4. Brief description: a description of what the routine does.
5. Expected: variables that the routine expects to be already set up in order for it to run as planned.
6. Locals: variables that are local to the routine; i.e., those that do not exist outside of the routine.
7. Results: Results of routine--what has been done, and variables set up.

The purpose of having a standardized header is to:

• make it easy to spot the routine visually
• make the routine name stand out so that it is easily visible
• make the code more readable

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

See Section 5.2, GOLD/R Routine Header Template Keystroke for instructions on automatically creating a routine template using a specially mapped keystroke in SPDEV.

The routine name appears directly under the header.

The body of the routine must be indented two spaces beyond the header and routine name.

The end routine statement should be the last statement in the routine.

Example 1-9 Routine Name and Body

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

1.1.7 Routine Coding Rules

Programs will be written in a top down format. The routines will follow each other lexically and be of a modular format. The following basic rules apply to programs and routines:

RULE

Keeps routine logic simple.

REASON

One operation/idea per routine is the easiest to follow. The single most important point about program structure is to put each small "concept" within the program into a separate routine. Use subroutines as a packaging mechanism to organize the individual thoughts and concepts in the program. How small a concept is will be subjective, but the smaller the thoughts or concepts you break a program into, the more successful you will be writing code.

EXAMPLE

Example 1-10 Keeping Routine Logic Simple

!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ! I n i t i a l i z a t i o n !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% . . !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ! M a i n L o g i c A r e a !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ask_generic_filename . . stop !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ! R o u t i n e s !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ! a s k _ f o r _ a _ f i l e n a m e !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ! ! Brief description: ! This routine asks for a generic filename (one ! which may include wildcards). ! ! Expected: ! . ! .

RULE

When calling a subroutine, the subroutine must lexically follow the routine which calls it.

REASON

Ensures that top down programming will occur. This encourages an outline form whereby routines are ordered from major to minor.

EXAMPLE

Example 1-11 Order of Routines

!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ! I n i t i a l i z a t i o n !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ! M a i n L o g i c A r e a !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ask_generic_filename . . stop !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ! R o u t i n e s !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ! a s k _ g e n e r i c _ f i l e n a m e !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ! ! Brief description: ! This routine asks for a generic filename (one ! which may include wildcards). ! . ! . ! . !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% routine ask_generic_filename . . . end routine

See Section 5.4, GOLD/O to Organize Routines for instructions on how to automatically order your routines using a specially mapped keystroke in SPDEV.

RULE

The body of the routine may not exceed 25 lines. Note: The lines from the line following the routine name, up to the line consisting of the end routine command, constitute the body of the routine.

During debugging, and where debugging code is used in the routine, this rule may be violated. However, debug code should be removed when the final routine is finished.

REASON

25 is the number of lines that can appear at one time on most laptop monitors. This makes it easier to read and to follow the code. It will also ensure that the code is simple, straightforward and extremely modular.

If a routine is trying to do too much, this rule will require that it be broken into several smaller routines. Programmers will be less likely to make mistakes if the code is shorter and can be viewed on one screen.

EXAMPLE

Example 1-12 Routine Length

!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ! c h e c k _ l i n e !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ! ! Brief description: ! . ! . ! Expected: ! . ! . !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% routine check_line filinx = filinx + 1 file$ = findfile$(generic_file$, filinx) if file$ = '' then done = true if not done then file$ = element$(file$,1,';') message 'Working on ' + file$ !++ debug jm ++ end if end routine

The routine in the example below is longer than 25 lines and must therefore be broken into two or more smaller routines:

Example 1-13 Long Routine

!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ! c h e c k _ l i n e !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ! ! Brief description: ! This routine has two functions: ! 1. To keep track of the current and previous ! line numbers to determine whether it is ! appropriate to insert the %include ! statement. ! 2. To keep track of whether the text is part ! of a function definition. If it is, the ! flag 'okay' is set to false so that it ! won't be transferred to the output file. ! ! Expected: ! . ! . !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% routine check_line previous_line = '' z0 = 0 line_begin = false next_okay = false when exception in line_nbr = val(text$[1:5]) use line_nbr = 0 end when if line_nbr > 0 then previous_line = current_line current_line = line_nbr line_begin = true end if z0 = skip(text$, '0123456789 ') if z0 > 0 then if text$[z0:z0+3] = 'DEF ' then okay = false elseif text$[z0:z0+4] = 'FNEND' then next_okay = true end if end if end routine

There are two simple clues that this routine is too long. One, the description states that it does two things. Each routine should do only one thing. Second, it exceeds the 25-line limit.

Below is the routine broken up into two smaller, more understandable routines:

Example 1-14 Smaller Routines

!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ! c h e c k _ l i n e !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ! ! Brief description: ! This routine is to keep track of the whether ! the text is part of a function definition. If ! it is, the 'okay' flag is set to false so that ! it won't be transferred to the output file. ! ! Expected: ! . ! . !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% routine check_line z0 = skip(text$, '0123456789 ') if z0 > 0 then if text$[z0:z0+3] = 'DEF ' then okay = false elseif text$[z0:z0+4] = 'FNEND' then next_okay = true end if end if end routine !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ! c h e c k _ l i n e _ n u m b e r !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ! ! Brief description: ! Check the text line for a line number and ! assign it to a variable. This is so that we ! can keep track of the current and previous ! line numbers to determine whether it is ! appropriate to insert the '%include' statement. ! ! Expected: ! . ! . !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% routine check_line_number previous_line = current_line line_begin = false next_okay = false line_nbr = val(element$(text$,1,' ')) if line_nbr > 0 then previous_line = current_line current_line = line_nbr line_begin = true end if end routine

See Section 5.3, GOLD/R to Create Subroutines for details on how to automatically create a subroutine from within a routine using a specially mapped keystroke in SPDEV.