Naming Variables and Functions in Scripts

A friend recently asked me about how I name variables in my FrameScript scripts. I used to use a “v” prefix on all of my variables names. For example, for a paragraph I would use:

Set vDoc = ActiveDoc;
Set vPgf = vDoc.MainFlowInDoc.FirstPgfInFlow;

The “v” prefix would simply indicate that I was setting a variable. This is the convention I used in my 2003 FrameScript book FrameScript: A Crash Course. Later, I decided to make the prefixes reflect the data type that the variable represents. I replaced the “v” with another letter indicating the data type. For example,

Set oDoc = ActiveDoc;
Set oPgf = oDoc.MainFlowInDoc.FirstPgfInFlow;

The “o” prefix means “object” since both lines set variables for FrameMaker objects. I use “s” for strings, “i” for integers, “r” for real numbers, “m” for metric values, etc. These prefixes help me see at a glance what kind of data type the variable represents. This is important when I am looking at a script that I may not have worked on in awhile. Prefixes like this are also helpful when you are reusing functions. For example, here is a function that applies a named paragraph format to a paragraph.

Function ApplyPgfFmt oPgf sName oDoc
//
Local oPgfFmt(0);

Get Object Type(PgfFmt) Name(sName) DocObject(oDoc) NewVar(oPgfFmt);
If oPgfFmt
  Set oPgf.Properties = oPgfFmt.Properties;
Else
  Set oPgf.Name = sName;
EndIf
//
EndFunc //-------------------------------------------

Even if I don’t know exactly how this function works, I can see at a glance that it takes three parameters: a paragraph object (oPgf), a string indicating the paragraph format name (sName), and a document object (oDoc). The prefixes help me to quickly see the data types of each parameter.

As far as the variable name itself, I try to use the object name that the variable represents. In the ApplyPgfFmt function, I use the Get Object command to get a PgfFmt object. So, I use oPgfFmt as the variable name. Using this convention lets me quickly see that oPgfFmt represents a PgfFmt object. The sName parameter gets matched up with Name in the Get Object command and so on. I find that this method helped me memorize the FrameMaker object model because I have closely associated my variable names with the built-in FrameMaker object names.

When naming functions, the common sense approach is to use some kind of a verb form that describes what the function does. When you look at the function name and its parameters, it should be evident what the function does without looking at the actual function code.

With ExtendScript, I do things a little bit different. I don’t use the prefixes, I simply use the object name but with a lowercase first letter. Here is the example I showed earlier:

var doc = ActiveDoc;
var pgf = doc.MainFlowInDoc.FirstTextFrameInFlow.FirstPgf;

ExtendScript (JavaScript) is a case sensitive language, so pgf is different from Pgf. For function names (and longer variable names) I use the “camel case” convention. I don’t use the datatype prefixes, mainly because this is not a normal convention for JavaScript programmers. I suppose it is a bit vain, but I don’t want my ExtendScript code to look too out-of-the-ordinary. Here is the ExtendScript version of the ApplyPgfFmt function:

function applyPgfFmt(pgf,name,doc) {

  var pgfFmt = 0, props = 0;

  pgfFmt = doc.GetNamedPgfFmt(name);
  if (pgfFmt.ObjectValid()) {
    props = pgfFmt.GetProps();
    pgf.SetProps(props);
  }
  else {
    pgf.Name = name;
  }
}