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 improve transparency of Analytica models.

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 a description 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 Platform (ACP).

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 this 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 widely known to model users.

It's often simplest to start with a noun phrase, like:

• The net present value of the cash flow.
• Not: This variable represents the net present value of the cash flow.

If the Definition code is complicated, it is better to add comments within the Definition explaining anything that may not be obvious, rather than include detailed explanation in 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.

See also

Document style guide: Guidelines for writing clear English, including Analytica documentation, like this Analytica wiki.

Analytica coding style

These guidelines are about making code in Analytica Definitions easier to read. We strongly recommend them for code examples in these docs, as well as in Analytica models and libraries:

Capitalizing text

Analytica, like most computer languages, ignores whether letters are upper- or lower-case (except when matching text values). But, these conventions can be very helpful for human readers:

• Capitalize -- i.e. first letter uppercase -- identifiers and titles of global variables, functions and other objects, such as

Speed_of_light, C, Sum()

• For longer identifiers, use CamelCase to separate words, such as

SpeedOfLight, DetermTable

• Use lowercase or camelCase (with first letter lowercase) for local variables and function parameters to distinguish them from global variables.
• Capitalize parameter qualifiers, for example:

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

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

• Use all uppercase for key words and constructs, like IF...THEN.. ELSE, BEGIN END, FOR... DO... VAR, METAVAR etc.

• In docs, 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.

Spaces

Analytica, like most computer languages, ignores spaces, tabs, and newlines. Again, 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 spaces around high-precedence operators "*", "/", and "^".
  • Do add spaces around 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 )

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. Analytica does that automatically when you create a function title, and offers to do so when you change a function title.

• Include in the title a list of parameters without qualifiers in parens. You 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, except small numbers, like 1 or 2. 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, from the Identifier, Title, and Description of the Constant.
• If the number needs changing -- e.g. when changing units -- you can do it in one place without having to inspect all the code.

This is a standard guideline for all computer languages, often ignored by inexperienced coders.

Newlines, tabs, and indents

Code is much easier to read if you use plenty of new lines to separate logical sections, and indentation to show code between BEGIN and END sections. This makes it easier for you as the writer of the code, as well as others that may need to review or modify your code.

In Analytica, you can use Tabs to add indents. In these docs (Mediawiki), put a colon, ":" at the start of each line.

Error messages

Error messages are often the worst written part of 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 writer)