How to make your formulas easier to understand

A long formula can be made more accessible by using Prettify, which applies some of the tips outlined below in a single click.

Tip 1 - Use line breaks, tabs and comments  

A great way to write a formula in Pigment is to structure it in a tabular way: keep the main content on the left, and as you look further right you get finer details.

Use line breaks and give some air to your formula. If you don't use line breaks, you can't really see the different meaningful parts of your data transformation. Also, Pigment conveniently places a keyword first when you read either a function or a modifier.

You can also comment out text by using a double slash. Use this to describe what this part of the formula does.

Here is an example of an indented formula with the original at the top:

1. No line breaks, no comments:

   

2. Line breaks, tabs and comments make for larger formulas, but they are easier to understand:

As you can see, a good combination of tabs, line breaks and comments already increases the formula’s legibility. If you move your eyes from left to right, you'll read first Revenue - minus - OPEX which is the main takeaway. The tabbed text provides a better understanding of how each is transformed.

You can read the modifiers in a tabular way: BY and FILTER for Revenue, and BY and BY SPLIT for OPEX. If you continue reading on the right, you can see the detailed rules for allocation and aggregation and you have enough space on each line to comment and justify why you went with this specific modifier or rule.

Tip 2 - End your parenthesis at the beginning of the line

If you have parentheses in your calculation, indent the content of your sub-calculation and then end the parenthesis at the beginning of the line. Otherwise it becomes very difficult to locate where your sub-calculation ends, thus making it more difficult to get the whole idea of how a formula works.

This example has a compact formula. Distinguishing the functional Blocks requires close reading:

In the treatment below, it is easier to identify what happens at first glance:

In this second version, you see quickly that there are two Blocks, which interact with each other via a multiplication. It's also much easier to identify the contents of those two main Blocks (Revenue-minus-Opex and Growth Rate).

Tip 3 - Factor your multiplications, additions and modifiers

Factoring modifiers often makes formulas more efficient and legible. In this example, both formulas perform exactly the same function:

The factored version is more compact and easier to read:

If it makes sense in your formula, grouping modifiers together can really make it easier to read.

Good formula hygiene

By using these simple rules and making them your own, you’ll decrease the time it takes for you to understand existing formulas in the Applications you’re building. This helps you identify potential errors in the reasoning or data alignment. By making your formulas clearer to read, you can pack more efficient, complex calculations while keeping everything easy to upgrade and to share.