Skip to main content

Adding comments to ATL

Comments are non-executable statements, written to aid human understanding. Adding comments to your ATL helps to explain your thought process and helps others to understand the intention of your code.

A comment must be inside an ATL block — i.e. somewhere between a pair of double square brackets ( [[ ]] ). Otherwise, Studio prints the comment verbatim in your project's output narrative.

The correct syntax for adding comments varies depending on whether you want the comment on a single line (wrappable) or organized into a multi-line block. See these sections for further guidance:

Method 1 — Single-line comments ( // )

You can start a comment with two forward slashes ( //).

When adding a comment at the end of an ATL block — that is, after the last ATL statement — there is no need to terminate the comment by inserting a line break or paragraph break. For example:

ATL in Script

[[unique(CountryColumn) // lists each unique value in Country column]]

Note

On smaller screens, the comment and last ATL statement might appear on different lines because of the editor's automatic line wrapping — the key point is you don't need to insert a break.

When adding a comment before any ATL statement, you must insert a break to terminate the comment.

ATL in Script

[[

// lists each unique value in the Country column 

unique(CountryColumn)

]]

Here is how you might add comments to a multi-statement ATL block:

ATL in Script

[[

// gets list of all values in Country column

allCountryValues = asList(CountryColumn)

// removes duplicate values from allCountryValues

uniqueCountries = unique(allCountryValues)

// amends uniqueCountries to add determiners (if applicable)

map(uniqueCountries, name -> countryDeterminer(name))

]]

Note that each comment is terminated by inserting a paragraph break. You could use line breaks instead.

Important

We have used bold text in each example to highlight the comment. This is not required in Studio.

Method 2 — Multi-line comments ( /* )

You can also define comments by wrapping them this way:

/* comment */

The advantage of this method is that you can split a single comment over multiple lines — that is, you can insert line or paragraph breaks within the comment itself without causing syntax errors. For example:

#value salesAnalytics (startDate, endDate)

[[

/* This function takes two parameters. 
The parameter values must be strings in a yyyy-MM-dd pattern.
The function filters the whole table by Date, then computes various Sales values.
The return value is a ATL object containing the calculated values. */

filteredData = filterRows(WholeTable, 'Date', value -> value >= startDate && value <= endDate)

sumVal = totalVal(columnsInRegion(filteredData, Sales))

avgVal = mean(columnsInRegion(filteredData, Sales))

medVal = median(columnsInRegion(filteredData, Sales))

topCountryData = groupByTable(filteredData, Country, Sales)[ :1]

topCountryName = topCountryData[0][0]

topCountrySales = topCountryData[0][1]

keys = makeList('sumVal', 'avgVal', 'medVal', 'topCountryName', 'topCountrySales')

values = makeList(sumVal, avgVal, medVal, topCountryName, topCountrySales)

createAtlObject(keys, values)

]]

The first four lines of the ATL block — that is, everything between /* and */ — comprise a single comment. Each line of the comment is separated by a line break. You cannot do this with the // method.

© Arria Data2Text Limited