Xbasic scripts that are properly written will run, whether or not they are formatted or left "as is." However, by using some simple formatting techniques, they can be MUCH easier to develop, read, and debug.

Just what do we mean by formatting? This is simply a way to add emphasis to different script commands and sections, and to add notes that describe what's happening. The key benefit to good formatting is that it helps you quickly see the general flow of the script ("what" not "how") so you waste less time finding the area of interest. Therefore, the primary goal when formatting program code is to identify basic script sections and program flow. It should be easy to view a script and quickly understand the basic flow by looking only at main comments and certain script highlights.

Why worry about readability? If you write a script, you will very likely need to review it sometime in the future. You might be doing this to update the script with improved techniques, or to add new features, or just to copy part or all of it to use somewhere else. Whatever the reason, trying to make sense out of a script that was written some time ago (which could even mean 'yesterday') can be a very frustrating and time consuming experience. This is where formatting can help.

Although many of the concepts that are presented here may seem like common sense, I must admit that I probably would not have used some of them, or would have taken a long time to stumble upon them, if it weren't for a couple of excellent instructors in my early programming classes. In addition to the ideas from these classes, the techniques are also based on my experience in writing and editing programming code - both my own and others. These are certainly not the only methods that can be used but they are proven techniques with a solid basis.

1.	Start with lower case. Otherwise, you can't use upper case for emphasis.
2.	Use indents for emphasis, and to define the flow of the program. •  Alpha Five automatically indents certain statements, such as IF..., SELECT..., WHILE. •  Indent embedded FUNCTIONs so you can quickly see where the function starts and ends. •  Indent program notes the same as the section they apply to.
3.	Use blank lines between logical sections to separate them. •  Add a blank line after every IF, WHILE, FOR, FUNCTION, or SELECT section (not including embedded IF statements). •  If you use labels (for a GOTO) in your code, make sure there is a blank line before and after every label. This makes them much easier to find.
4.	Use spaces between 'words' to make it easier to read. •  With spaces, you can double-click to cut-and-paste individual 'words', and use Ctl-[arrow key] to navigate to a 'word'. •  Use spaces before and after variable names and operators, such as =, >, .and., etc. For example, an expression with no spaces: name=var->sal+trim(dbh.fname)+" "+Trim(dbh.lname) The same expression with spaces: name = var->sal + trim(dbh.name) + " " + trim(dbh.lname)
5.	Capitalize text that defines program direction or execution, such as: •  COMMAND STATEMENTS, such as DIM, IF...END IF, GOTO, etc. •  MESSAGE HEADERS, used in ui_msg_box(), ui_get_list(), etc. will often help identify what's going on in the script.  Not only do they make the message more noticeable for the user, but they also help to self-document the script. •  NOTES to explain the intent of script sections.
6.	Use notes to explain each section of the script. •  Start each script with a note to indicate the purpose of the script. •  Use notes at the start of major script sections to indicate what the code in that section will accomplish. •  Indicate what form, button, or other script uses the current script. •  Add notes when the intent of the script is not obvious, such as explaining an unusual calculation, or how the script might affect other parts of the program. •  Add notes if the script is called by another script, or a global variable is set by another script. •  Determine, and stick to, a system to identify at least 3 different types of notes: major script sections, informational notes, and important notes about things that are either very unusual or could affect other parts of the application if changed locally. One guideline used for determining when something falls in the third group is to ask the question, "Should this note be reviewed before any changes are made to this section of the script?" If so, it falls in group 3.

Here's an example of a script, using the suggestions listed above:¹

'-----------------------------------------------

' FIND DRIVE LETTER FOR NETWORK SERVER

'-----------------------------------------------



DIM global adbname as c

DIM global drive as c



'--- GET CURRENT DATABASE NAME ("DATABASE.ADB")



filepath = :a5.get_name()



'--- DETERMINE CHARACTERS IN 'FILEPATH' 



IF chr(92) $ filepath

   adbname = right( filepath, rat(chr(92),filepath)-1)

  ELSE

   IF ":" $ filepath

      adbname = right( filepath, rat(":",filepath)-1)

     ELSE

      adbname = filepath

   END IF

END IF



'--- FIND DRIVE LETTER FOR SERVER



drive = "C"



'*** CHECK THE FOLLOWING PATH ON LOCAL MACHINE



FOR x = 1 to 24

   drive_path = drive + ":\compuniq\data" + chr(92) + adbname

   IF file.exists(drive_path)

      ui_msg_box("NETWORK DRIVE", "Drive is "+left( drive_path, 2) )

      END

   END IF

   drive = chr(val(ltrim(str(asc( drive )+1))))

NEXT x



ui_msg_box("SERVER DRIVE NOT FOUND", \ 

"The program could not locate the server.", 16)

END

Notice that each note line begins with the ' so that the program doesn't try to execute the note itself.

Please keep in mind that these techniques are not necessarily the only ways to format Xbasic scripts.  You might want to develop your own methods.  Remember that the main purpose of formatting is to help make your code easier to read and understand.

In next month's issue, we will talk about a related topic, Naming Conventions.  This will cover how to name objects, such as tables, fields, and layouts, as well as guidelines for what to avoid.

¹ The purpose of this script is to show formatting.  The actual function of the script is not important.
[PRINTER FRIENDLY VERSION]