Analytica model style guide

The design of Analytica, including influence diagrams and structured model documentation, encourage building models that are much more transparent than other modeling environments, especially spreadsheets. Even so, there are things you can do to improve -- or destroy -- transparency with Analytica, as with any modeling tool! These guidelines suggest ways to transparency in Analytica, and other environments too.

Descriptions

Clear descriptions make a model much easier to understand for reviewers, maintainers, and even the person who originally wrote the model a few months later. It is really helpful to include a brief description with every variable, module, and function.

Descriptions for user inputs and outputs

It is especially important to include descriptions for each user input and output, if your model has a user interface for end users. Your end users might not find the title of each object to be sufficient to explain the meaning of each variable, even if it's obvious to you, the model author. The user can see the description of each variable, user input or output, and even module in a balloon bubble, simply by moving the cursor over that element. This works the same in Analytica on the desktop as in Analytica Cloud Player.

Use imperative voice for user inputs and buttons

It's shorter and clearer to use the imperative voice:

Click this button to see the result

Not: The user should click this button to see the result.

Use second person, "you" or "your", as appropriate.

Select the state in which you live.

Not: The user must select the US state in which he or she lives.

For a checkbox:

Check box to include the results in the saved file.

Not: The user should check this box if he or she wants results to be included in the saved file.

Descriptions for other variables

Descriptions for variables should start with a clear description of what the variable represents. It's a good idea to expand any abbreviations that are not very widely known in this domain. It's often simplest to start with a noun phrase. No need to say "This variable is..." or "This represents ....":

If the Definition is complicated, it may be helpful to add a brief overview of what the calculation is doing at the end of the Description.

Fill out Units

It is very helpful to include Units for each variable. If it has no units (dimensionless), it's better to put "-" or "none" in the units than to leave it blank, so a reader knows that you intend it not to have units, and you didn't just forget to specify them.

Analytica language

These guidelines make code easier to read. We strongly recommend them for code examples in this wiki, as well as Analytica models and libraries:

Indent code lines by one tab, by putting a colon, ":" at the start of each line.

Colons are better than spaces because spaces are harder to see and count in wiki markup, the code is easier to read on the more contrasting white background than the gray background displayed with using spaces, and the true-type font is sufficient to distinguish code from the surrounding text.

Capitalize the first character of the identifier of global Variables, Functions and other global objects, such as Speed_of_light, C, Sum().
For longer identifiers, use CamelCase to separate words, such as SpeedOfLight, DetermTable.

Use uppercase for key words and constructs, like IF...THEN.. ELSE, BEGIN END, FOR... DO... VAR, METAVAR etc.
Use lowercase for identifiers of local variables and parameters in Parameter Definition, upper case for indexes parameters, for example

Function Quadrate(x, y, i, j)

Some people prefer uppercase for Index parameters, as in:

Function Quadrate(x, y, I, J)

Use right-arrow "→" to mean "the preceding expression generates the following result":

 10^5 → 100K

Use Suffix notation for numbers, unless there is a reason not to. It's clear, compact, and Analytica's default.

Using spaces

Analytica like most computer languages ignores spaces, tabs, and newline. But, these guidelines can help make the code easier to read and understand:

Use spaces to reinforce precedence of binary operators (how tightly operators bind to their operands before and after):
- Don't add space before and after high-precedence operators "*", "/", and "^".
- Do add a space before and after low-precedence operators +, -, =, <, <=, >=, >, <>

a + b*c/(d - e)^2 AND (x < y) OR (u = v)

Not: a+b *c/( d-e )^2 AND (x<y) OR ( u=v )

Add one space after, but none before, separators ",", ":" and ";"
Don't put space after an open paren or bracket "(" or "[", or before a close paren or bracket, ")" or "]".

Sum(10 + X, I) - (1 + X^2)/(X - 1)

Not: Sum( 10+X,I )-(1+X ^ 2 )/( X-1 )

Use these same guidelines for function parameters (actual or formal parameters):
- No space after or before "(" and ")".
- A space after but not before separators ",", ":" and ";"

Function Extra(a: Number; t: Text; flag: Optional = True)

Not: Function Extra( a : number ; t :text;flag : optional = True )

Upper and lowercase

Analytica, like most computer languages, also ignores letter case (except when matching text values). But, these conventions can be very helpful:

Use Sentence case -- i.e. first letter uppercase -- for identifiers and titles of global variables, functions and other objects.
Use lowercase or camelCase for formal function parameters and local variables declared in a variable or function to distinguish them from global variables. (Some prefer to use uppercase for index parameters, like I, J, K.)
Use uppercase first letter for qualifiers
Use all uppercase for language constructs including IF, THEN, ELSE, BEGIN, END, VAR, LOCAL and so on.

Function F(x: Number; I: Index; camelCaseX: Optional Text)

Not: Function F( x : number; i:Index ; CamelCaseX : optional text)

Function titles

The Title of a user-defined Function should be identical to its identifier, using underscore "_" to replace any spaces or other non-alphanumeric chars. Add in a list of parameters without qualifiers in parens. The parameter list can omit rare optional parameters. That makes it easy to find and select Functions from a library -- e.g.

Function Flatten_array

Title: Flatten_array(x, I, J, K)

Parameters (x: [i, J]; I, J, K: Index)

= Don't embed numbers in definitions

Don't embed numbers, like conversion constants, in definitions. Instead define a Constant to contain the number, and use the Constant in any Definition that uses it. The advantages are:

It makes it clearer what the number means
If the number needs changing -- e.g. when changing units -- you can do it in one place without having to inspect all the code.

Error messages

Error messages are usually the most horribly written part of most software (perhaps second only to the license agreement). It's often worth spending some time to make them clear and useful. An error message should be

Friendly. If it's a deficiency in the model or software, -- e.g. no more space for something -- it could start out by saying "Sorry", to acknowledge a mistake or deficiency of the programmer/modeler or possibly writer of the operating system. If the user does the wrong thing or is confused, that is arguably a deficiency in the program or model or documentation -- so again, "Sorry" is often appropriate.
Say what went wrong in terms that will be comprehensible to the average or even a novice user.
Tell the user what they should do about the problem --unless it is totally obvious from explaining what went wrong (to the user, not just the modeler