Using Comments Effectively

Most programming and development environments give you some way to add comments to a system. Comments are descriptive information that you, the developer, supply throughout the system to clarify the meaning and usage of programming constructs. When commenting your work, try to keep two goals in mind: explaining why something exists or does something, and describing what the expectations around it are. Answer the questions "What goes in?" "What comes out?" and "Whats its purpose?"

Adding Comments for Fields

The Define Database dialog allows developers to add comments to fields. Each comment can be up to 30,000 characters in length. The selected fields comment is displayed under the field name. View all comments by clicking the Options/Comments column header at the top of the field list. Field comments are included in the Database Design Report (covered later in this chapter) and are also accessible via the Get ( FieldComment ) function. Figure 27.1 shows an example of field comments.

Figure 27.1. Field comments can be displayed in the Fields tab of the Define Database dialog.

Commenting Within Formulas

Formulas are defined in various places, including calculation fields, field validation, and some script steps such as If, Set Field, Set Variable, and Replace Field Contents. C-style and C++style comments are both supported within calculation formulas. C-style comments begin with the characters /* and end with the */ characters. C-style comments can span multiple lines and can be nested within other comments. C++style comments begin with // and continue through the end of the line. Here are a couple of examples:

/* concatenate authors name in the form last, first
 example: Smith, John */

name_last &

Case(WordCount(name_first) and WordCount(name_last);
", ") //don	 include comma if either field is empty

& name_first

Scripts

The Comment script step can be added anywhere within a script. Up to 30,000 characters may be included in the dialog box. Within ScriptMaker, the Comment script step appears in bold text, preceded by a # character. When a script is printed, the Comment script step is in italic.

Heres a real-world example of a script that runs the first time a user opens the database. It represents what wed consider good commenting:

OnOpen
# purpose: Default script that runs on first opening the file
# (set via the File Options dialog)
# dependencies: security privileges; tests for full access
# NOTE: This database currently doesn	 restrict access to the status area
# or toolbars; however, if you wish it to, modify the lock down section
# below.
# history: scl 2004sep22; slove2005jun22 added whosIN logging;
# slove 2005jun28 added session handlers
#
# Create new session (every person logged in should have their
# own session record in the session table)
Perform Script [ "CreateNew_SessionRecord" ]
#
# Restore Globals (loads default settings)
Perform Script [ "__Restore_Globals" ]
#
# Set WhosIn (record the account name of the person
# logging in on the Admin layout)
Perform Script [ "__Add_WhosIn" ]
#
# Error Handling (uses custom function to toggle debug mode in scripts on/off)
If [ fnDebugMode ( DEVH__Home~tog::LoggedIn_Account_gt ) images/U2260.jpg border=0> 1 ]
Allow User Abort [ Off ]
Set Error Capture [ On ]
End If
#
# test for Full Access privileges
If [ Get ( PrivilegeSetName ) = "[Full Access]" ]
Perform Script [ "Unlock_for_development" ]
Else
#
# NOTE: this system is currently OPEN
# to lock it down, simply change the settings below
Allow Toolbars [ On ]
Show/Hide Status Area
[ Show ]
End If
#
# Set initial window position
Perform Script [ "__Default_Window" ]
#
# Make sure the logged-in person has a corresponding People record
Perform Script [ "Check_RelatedPersonRecord" ]
#
#
# Open dev tools if full access (opens a layout exclusively used by developers)
If [ Get ( PrivilegeSetName ) = "[Full Access]" ]
Perform Script [ "Show_Developer_ToolsPalette" ]
End If
#

Adding Descriptions in the Define Accounts & Privileges Dialog

Accounts, privilege sets, and extended privileges can each have associated descriptions. Enter a description when defining these items in the Define Accounts & Privileges dialog box. Up to 30,000 characters may be included for each. The descriptions appear in their respective lists and are also included in the Database Design Report.

Figure 27.2 shows a real-world example.

Figure 27.2. Be certain to add descriptions to privilege sets; this information is helpful within this dialog and in the Database Design Report.