Using Comments in Formula Columns

ccastleman · ‎05-25-2022

Introduction

Commenting code can make things much easier for yourself and others to understand what the particular code or function is doing. Incorta Formula columns are no exception and well placed and structured comments can be quite useful.

What you need to know before reading this article

Formulas are created and edited in Incorta using the Formula Builder user interface. For more information please review the Incorta documentation.

Applies To

All Incorta Releases version 5.1.2 and newer.

Let's Go

The Formula Builder supports using comments in the Formula Editor as follows:

// Single line comment
/* Multi-
line
comment */

The majority of Formula columns in Incorta are very simple and do not require additional comments to explain what is happening. Formulas that are simply using prebuilt functions for example may be self explanatory. However, even a simple Formula might have a business purpose that may not be clear in the code itself. In these cases it might make sense to add a simple comment about the reason for this particular Formula or how it is to be used.

Simple (self explanatory) Formula expression

A simple Formula usually does not require comments. For example:

substring( EPM_PRODUCT..product.product, 2)

However it may need to be spelled out why this is being done:

/*remove EPM leading 2 characters of Product to match EBS Item,

used for join between EBS and EPM*/

substring( EPM_PRODUCT..product.product, 2)

Complex Formula Logic

Some Formulas may be more complex and in these cases it is usually helpful to add comments to explain the logic of the branches or sub-functions.

/*Filter data in Insight using date range selected from a dashboard prompt and using global variable for current date*/

or(
and(
$pv_DatePeriod = "Previous Day", //yesterday only
daysBetween(
$currentDate,
SALES.SALES.curr_date
) = 1
),
and(
$pv_DatePeriod = "Previous 30 Days", //past 30 days only
daysBetween(
$currentDate,
SALES.SALES.curr_date
) < 30
),
and(
$pv_DatePeriod = "Previous 90 Days", //past 90 days only
daysBetween(
$currentDate,
SALES.SALES.curr_date
) < 90
),
and(
$pv_DatePeriod = "None", //do not filter
1 = 1
)
)

Related Material

There are a myriad of best practices articles about commenting code available on the web. Here are a few good ones: