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?"
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.
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
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 #
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.
Part I: Getting Started with FileMaker 8
Using FileMaker Pro
Defining and Working with Fields
Working with Layouts
Part II: Developing Solutions with FileMaker
Relational Database Design
Working with Multiple Tables
Working with Relationships
Getting Started with Calculations
Getting Started with Scripting
Getting Started with Reporting
Part III: Developer Techniques
Developing for Multiuser Deployment
Advanced Interface Techniques
Advanced Calculation Techniques
Advanced Scripting Techniques
Advanced Portal Techniques
Debugging and Troubleshooting
Converting Systems from Previous Versions of FileMaker Pro
Part IV: Data Integration and Publishing
Importing Data into FileMaker Pro
Exporting Data from FileMaker
Instant Web Publishing
FileMaker and Web Services
Custom Web Publishing
Part V: Deploying a FileMaker Solution
Deploying and Extending FileMaker
FileMaker Server and Server Advanced
Documenting Your FileMaker Solutions