Overview

In general, PhixFlow ignores all spacing around the functional elements. However spacing and layout makes the meaning much clearer for you to read. Adopting a common, shared, standard style for all expressions, scripts and macros makes it easier to read them and quickly understand what they are doing.

This page provides recommended styles for writing expressions.

General

• Item properties
  • All items in PhixFlow have a description property. We recommend you add a description to any item you create.
    Anybody looking at a model or application will first look at the descriptions of the items within it.  For example, in an analysis model, they should be able to discern the flow and the high-level logic of the model just from the descriptions.
  • In analysis models, the stream description should explain the use of input or output multipliers. This it typically a significant part of any model.
  • Ensure that attributes that represent the same thing in different streams have the same name. PhixFlow needs this when processing merges and for a union in a calculate stream.
• Formatting expressions
  • Add comments to document your expression using:
    
    • // for a single line comment
    • /* ... */ to enclose multiline comments
  • Include blank lines between statements
  • Use spaces within expressions
  • Indent sub-clauses by 4 spaces

Naming Conventions

Multi-word stream attribute and pipe names should be in camel case.

• All user-defined variables must start with the $ character. 
• For multi-word variable names, use no spaces and camel case.
• It can be useful to know whether a variable is used in other expressions. As there is no way to check this, we recommend using the following naming convention:
• To distinguish between $-variables that are:
  • only used in the current expression or attribute, use a lowercase first letter, for example $percent. 
    These are sometimes called local.
  • used in other expressions or attributes, use an uppercase first letter, for example $Percent.
These are sometimes called global. 

Adding Comments

It is always a good idea to add comments to your scripts to explain its steps. Comments help anyone who needs to modify the script in future.

There are two ways to tell PhixFlow that a line is a comment, and can be ignored.

Comments are not evaluated when the code is run.

/* Get the discount rate that should apply to 
the calls that match the filter conditions */

$discountRate = discount.rate,

// Now apply the discount

$value = $value * ( 1 - $discountRate)

...

/* Evaluates to 1 if AppleHarvest Date is Before 1st January 2021*/
if( _out.AppleHarvestDate < _toDate('20210101'), 1,
    
// else, 0 if it is not
	0
)

Layout for if()

Simple

For simple if() statements we recommend the following style of layout:

Note that when a statement in an if() clause is more than 1 line, wrap them in a do(), for example:

// Example code layout 
if( condition expression,
    do(
        Statement 1,
        Statement 2,
        ... Statement n
    ),
 
// else
    Statement A
)

Complex

For more complex if() statements we recommend the following style and that comments are added:

// Short description on what is being achieved when the if statement is true
if ( $foo > 10 &&
     $bar == "X" &&
      ( $baz == "Y" ||
         $qux == "Z" ),
 
    // description of what the statement is doing
        do (
               Statement 1
        ),
 
// else, description of what the statement is doing
    Statement 2
)

Layout for switch()

Simple

For simple switch statements we recommend the following layout:

switch(
    [ condition expression 1, Statement 1 ],
    [ condition expression 2, Statement 2 ],
 
// default
    _NULL
)


// example
switch(
    [ $foo > 100, $x = "HIGH" ],
    [ $bar > 50,  $x = "MEDIUM" ],
 
    // default
    $x = "LOW",
)

Complex

For switch statements that perform more advanced activities we recommend the following layout:

switch (
      // description of what the statement is doing
      [ $foo == 100,
           $x = "HIGH"
      ],
 
      // description of what the statement is doing
      [ $bar == 50,
           do (
                 $x = "Medium",
                 $x = toUpper($x)
           )
      ]
       
      // default
      do (
           $x = "LOW"
      )
)