| Previous | Contents | Index |
// comment text
|
| Example 3-21 Comments in Programs |
|---|
input 'Please enter your name': name$ // ask for a name print 'Hello, '; name$ // say hello end Please enter your name? Mike Hello, Mike |
All programs should be well documented with comments. Comments teach future programmers, as well as yourself, how a program works. The proper use of comments can dramatically enhance the ability to maintain a program.
Comments are used to put headers in routines, and to comment code within routines. Always document code thoroughly in each routine header. Ideally, commenting should rarely be done inside the actual routine. If the routine is written simply and kept short, then no comments are needed within the code. Keep the size and scope of the routine limited and obvious for future reference.
Comments are used to clarify parts of your program as shown in the example above.
When the program source code is listed or printed, the commented line is displayed as it was written.
When Sheerpower executes the above program, it executes the INPUT statement, ignores the "//" and the comment text following it, and continues execution at the PRINT statement. The "//" does not have to be placed at the beginning of a physical line. It can be indented on its own line, or placed at the end of a line of code as well. For example:
// this comment will work
// this comment will also work
input 'Tell me your name'; name$
print 'Hi there '; name$ // this comment works too
end
Tell me your name? Suzanne
Hi there Suzanne
|
In SPDEV, the GOLD/r keystroke automatically creates the routine header template. The 'GOLD' keys in SPDEV are the [Esc] (Escape) key or the [NumLock] (Numbers Lock) key. For more special keystrokes in SPDEV, refer to Appendix F, Keystrokes for Sheerpower Rapid Development Environment.
Below is an example of a Routine Header used to document each routine:
| Example 3-22 Routine Header Sample |
|---|
!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ! f i n d _ p e a k _ c a m s _ a n d _ v i e w e r s !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ! ! Brief description: ! This routine finds the peak number of cams logged in and peak ! number of live viewers watching each day. ! ! Expected on entry: ! total_live_viewers = number of live viewers ! live_cameras = number of live cams ! ! Locals used: ! none ! ! ! Results on exit: ! peak_viewers = peak number of live viewers ! peak_cameras = peak number of live cameras ! !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
The double-forward slash "//" can be used after an ampersand to document continued lines in a program. When a line of code is continued with an ampersand, any comments must follow the ampersand. For example:
| Example 3-23 Comments With Line Continuation |
|---|
input a$
if a$ = '' then print a$; & // here is the trailing
' is OK.' // comment text
end
|
Code that is inserted into a program for the sole purpose of debugging the program should be marked with a debug comment. Sheerpower can automatically create a debug comment line for you with a special keystroke.
The GOLD/C keystroke is mapped to create a debug comment line. In SPDEV, a GOLD key is a special key that allows you to utilize other keys for different purposes. The GOLD key is either the [Esc] (Escape) key or the [NumLock] (Numbers Lock) key. See Appendix F, Keystrokes for Sheerpower Rapid Development Environment for more special Sheerpower Rapid Development Environment keystrokes.
To perform the GOLD/C keystroke, place the cursor where you want the debug comment line created. Press once on the [Esc] key or the [NumLock] key. Let go and look in the bottom right hand corner of the SPDEV window. Sheerpower tells you if your GOLD key is activated by highlighting a small square in the bottom frame in black, with gold letters that say 'Gol'. Now you can press the [C] key, and a small dialog box will appear asking you for your initials. Leaving your initials will allow future programmers (as well as yourself) to know who inserted this line of debug code. Enter your initials, and click on 'OK'.
| Example 3-24 Debug Comments |
|---|
!++ debug SMW July 20, 2015 |
The '!++' at the beginning of every line of debug comment makes it very easy to perform a search and find all lines containing debug code.
The following sections describe the directives that are available for use in your programs. These directives are invoked when the compiler builds a program and/or when a program is compiled.
%COMPILE 'quoted_text'
|
| Example 3-25 %COMPILE Program Directive |
|---|
print 'This is a test program.' %compile 'Text that you want to be seen inside the SPRUN file...' %compile 'Up to 100 lines of text can be seen here!' end |
Using the DEPLOY feature you can make portable runnable applications (.SPRUN files). These files are plain text, and can be password protected.
SPRUN files allow you to distribute Sheerpower programs without your source code being seen.
An SPRUN file can be easily copy/pasted, emailed or embedded into a website. This allows for simple distribution of an application.
The %compile text is truncated at 72 characters. There can be up to 100 %compile text lines in a program.
Once the text is inside the SPRUN file, if it is altered in any way the SPRUN file will not run! This is a good place to put copyright notices and license agreements, etc.
%MESSAGE 'quoted_text'
|
| Example 3-26 %MESSAGE Program Directive |
|---|
%message 'Including HELP module' %include 'sptools:help' end |
This compiler directive displays a message, quoted_text, on the message line. The message is displayed when a program is built into a workspace or compiled.
%MESSAGE ERROR: 'quoted_text'
|
| Example 3-27 %MESSAGE ERROR Program Directive |
|---|
%message error: 'Using experimental HELP module' %include 'sptools:help' end |
This compiler directive makes an alert sound and displays the message when a program is compiled.
%INCLUDE 'file_spec'
|
| Example 3-28 %INCLUDE Program Directive |
|---|
%include 'sptools:example' |
%INCLUDE allows you to put common subroutines into a separate file to be shared among applications.
%INCLUDE includes a source code file into the current Sheerpower program. The default extension for a Sheerpower included file is .SPINC.
%include conditional: 'file_spec'
|
If the file to be included does not exist, no error is generated. This allows programs to conditionally include modules.
%INCLUDE CONDITIONAL includes a source code file into the current Sheerpower program if the file to be included is found. The default extension for the included file is .SPINC.
%DEBUG Sheerpower_statement
|
| Example 3-29 %DEBUG Program Directive |
|---|
%debug print 'DEBUG Items' end DEBUG Items |
The %DEBUG directive gives an error only if an image compile (/COMPILE) is being done. A %debug statement will return a fatal error when you attempt to VALIDATE or DEPLOY the program. Use this directive to make sure that DEBUG code does not show up in production applications.
| Previous | Next | Contents | Index |