| Previous | Contents | Index |
Where it is necessary to make a routine longer than 25 lines, you must specify in the routine header why it is longer than 25 lines.
Ensures that routines will not be longer than 25 lines whenever possible. (On occasion, for instance where a table is used in a routine, it will be necessary to exceed the 25-line limit.)
| Example 1-15 Commenting Long Routines |
|---|
!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
! m a i n _ m e n u
!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
!
! Brief description:
! This is the main menu for end of month
! processing. This module exceeds standard length
! because of the case statement.
!
! Expected:
! .
! .
!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
routine main_menu
display_menu
do
input "Enter item:"; choice$
good_choice = true
select case choice$
case 'EOM'
end_of_month
case 'EOQ'
end_of_quarter
case 'EOY'
end_of_year
case 'MTOT'
monthly_totals
case 'BALSHT'
balance_sheet
case 'INCOME'
income_stmt
case 'SALES'
sales_report
case 'PROD'
production_report
case else
print "Not a valid choice. Please re-enter."
good_choice = false
end select
loop until good_choice
end routine
|
Routines should be separated by three blank lines. The last line of the routine (the line containing the end routine statement) should be followed by three blank lines, then the header line for the next routine.
Makes routines easily visible and more readable, and to make searches easier.
.
.
.
end routine
!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
! c l o s e _ o u t
.
.
.
|
The following rules apply to all code written. Programs, routines, and revisions to current code must comply with these rules.
All code will be written in lower case. No upper case letters are allowed except in documentation and within quotes.
Makes code easy to read.
| Example 1-16 Writing Code in Lower Case |
|---|
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 |
See Section 5.10, GOLD/DOWN and UP Arrow to Change Case for instructions on how to automatically convert all unquoted code/text to lower case using a specially mapped keystroke in SPDEV.
Variable names should closely resemble their function. Some variables are automatically initialized, so there is no need to initialize them within your code. However, some programs consist of many modules that will not be initialized automatically.
Makes it easy to tell the purpose of the variable.
| Example 1-17 Variable Names |
|---|
Line_counter Line counter
Page_counter Page counter
database_engine_menu Database engine menu
student_name Student name
|
Make use of SheerPower internal variables; i.e., _BACK, _EXIT, _HELP.
These are automatically set and cleared by SheerPower.
| Example 1-18 SheerPower Internal Variables |
|---|
do
input 'Please enter your name' : name$
if _exit then
print '_exit is set to true'
exit do
end if
loop
end
|
Always line up "=" signs.
When declaring variables, listing them alphabetically makes them easy to find. Initialize variables at the top of the routine.
| Example 1-19 Lining Up " =" Signs in Routines |
|---|
html_dailystats$ = "c:\sheerpower\dailystats.html" temp_dailystats$ = "c:\sheerpower\dailystats.tmp" html_camstats$ = "c:\sheerpower\camstats.html" temp_camstats$ = "c:\sheerpower\camstats.tmp" html_sitestats$ = "c:\sheerpower\sitestats.html" temp_sitestats$ = "c:\sheerpower\sitestats.tmp" temp_caminfo$ = "c:\sheerpower\camera_info.tmp" text_caminfo$ = "c:\sheerpower\camera_info.txt" |
See Section 5.5, GOLD/A to Align Equal Signs "=" for instructions on how to automatically line up "=" in your code using a specially mapped keystroke in SPDEV.
Debug code includes debug statements and code used in the process of debugging. Debug code should be removed from the final version of any routine, once the bugs have been found and resolved.
Two blank lines must appear both before and after each block of debug code.
Ensures visibility and provides an easy way to search for debug code.
| Example 1-20 Debug Code |
|---|
open #in_ch: name file$ !out$=element$(file$,1,".BAS")+".NOD" !++ debug jrm ++ out$ = 'TT:' !++ debug jrm ++ open #out_ch: name out$, access output |
Every line of debug code must be specially noted. Code which is added for debugging purposes must be designated with a comment at the end of each line of debug code. The comment should look like this:
| Example 1-21 Debug Code |
|---|
!++ debug programmers_initials ++ |
The !++ and the word "debug" indicates that this is debug code. The programmer's initials should follow, and then another set of double plus signs.
This designation will clearly mark debug code, and specify the programmer who performed the debugging in case they need to be contacted. The !++ provides a unique search text to use with the SPDEV FIND function. The programmer can search for leftover debug code by performing a FIND using either the FIND button in the toolbar, or by pressing Ctrl/F.
They can then delete just the debug code lines rather than a block of code (and possibly deleting non-debug code, as well).
| Example 1-22 Debug Code |
|---|
open #in_ch: name file$ !out$=element$(file$,1,".BAS")+".NOD" !++ debug jrm ++ out$ = 'TT:' !++ debug jrm ++ open #out_ch: name out$, access output |
See Section 5.6, GOLD/C to Insert Debug Comment Line for instructions on how to automatically generate debug comments using a specially mapped keystroke in SPDEV.
Structures should be opened and closed only once in a program.
The overhead of opening and closing files is wasteful.
Screen prompts should be located at the bottom left side of the screen. They should use a question mark instead of a colon prompt.
Ensures that the prompts can be easily found.
Input information should be displayed to screen in BOLD after the information has been input.
Makes user-entered data stand out from the screen background.
line input at 21, 1, prompt 'Name?' length 30, erase: reply$ print bold, at 3, 15, erase: reply$ |
Use boolean variables (indicated by a trailing "?") as TRUE/FALSE flags.
Clarifies that the variable is a flag and not a quantity.
do
line input #in_ch, eof got_eof?: rawdata$
if got_eof? then exit do
print rawdata$
loop
|
Strict indentation rules will be enforced in any code. Consistent indentation rules make it easier to do searches and global replacements. They also make the code easier to read and therefore easier to maintain. The following rules apply:
Code should be indented 2 spaces underneath the routine name.
Makes code neater, which is easier to read and follow. Additionally, searches will be easier as the number of spaces is predictable.
| Example 1-23 Code Indentation |
|---|
routine print_report 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 end routine |
See Section 5.11, Tab Key to Indent for instructions on how to easily adjust code indentation using a specially mapped keystroke in SPDEV.
IF THEN statements must contain two spaces between the IF and the condition, and two spaces between the condition and the THEN. If a block construct IF THEN is used, the block of code must be indented two spaces under the IF THEN statement.
Makes code neater and easier to read. Also makes searches easier.
| Example 1-24 IF THEN Statement Spacing and Indentation |
|---|
if text$[z0:z0+3] = 'DEF ' then
okay = false
elseif text$[z0:z0+4] = 'FNEND' then
next_okay = true
end if
|
Where several conditions are specified in an IF THEN statement, the following format is to be used:
| Example 1-25 IF THEN Format |
|---|
if condition operator &
condition then
---
--- block of code
---
end if
|
For example:
| Example 1-26 IF THEN Format with Multiple Conditions |
|---|
if (previous_line < include_line_nbr) and &
(current_line > include_line_nbr) and &
(line_begin = true) then
print #out_ch: iline$; '%include cursor_def.inc'
print #out_ch: ' %include common_def.inc'
print #out_ch: ' %include misc_def.inc'
print #out_ch:
end if
|
| Previous | Next | Contents | Index |