Syntax Basics: Statements, Comments and Names

This lesson is the boring one, and it is short for that reason. It covers the mechanical rules AFL enforces — where semicolons go, how to write a comment, what counts as a legal name — plus the conventions this course uses, which AFL does not enforce and which matter more.

Get these right and the interesting lessons stop being interrupted by punctuation errors.

Statements and semicolons

An AFL formula is a sequence of statements. Every statement must end with a semicolon.

Fragment — not a complete formula

MaPeriod = 50;
Average = MA( Close, MaPeriod );

The semicolon is a terminator, not a line separator, and the difference is useful. A single statement may span as many physical lines as you like — AmiBroker keeps reading until it meets the semicolon. That is how a long expression stays readable:

Fragment — not a complete formula

Tradeable = Close > MA( Close, 200 )
            AND Volume > MA( Volume, 50 )
            AND Close > 5;

That is one statement across three lines, and it is easier to read than the same thing crammed onto one. The course uses this layout constantly for conditions with several parts.

The corollary is the error you met in the last lesson. Because the parser keeps reading past a line break, a missing semicolon is not detected on the line where it belongs — it is detected on the next line, when something turns up that cannot possibly continue the statement. Error 32 says so in as many words: “probably missing semicolon at the end of the previous line”. The same error also fires for a stray character at the start of a line, such as an accidental + left over from an edit.

Braces group statements

Curly braces { } turn several statements into one compound statement, so that a construction expecting a single statement can be given a block of them:

Fragment — not a complete formula

if( BarCount < 200 )
{
    _TRACE( "Not enough history for this study." );
    _TRACE( "Nothing will be calculated." );
}

Without the braces, only the one statement immediately after if( ... ) belongs to it, and the second _TRACE() would run unconditionally. This is a mistake that produces no error message at all, which makes it worth a habit: put braces on every block, even a one-statement one. The cost is two characters.

!Important

Braces group statements. In many languages they also create a new scope, so that a variable declared inside a block disappears at the closing brace. In AFL they do not. Scope is decided only by whether a name first appears inside or outside a function definition. A variable first assigned inside an if block is visible after it. Part 11 covers scope properly; for now, simply do not expect braces to hide anything.

Comments

AFL has the two comment styles C programmers will recognise.

Fragment — not a complete formula

// Everything after two slashes, to the end of the line, is a comment.

/* A block comment starts with slash-star and ends
   at the first star-slash it meets, however many
   lines later that is. */

Average = MA( Close, 50 );   // a comment can also follow real code

One rule catches people out: comments do not nest. A /* inside a block comment does not open a second comment. The block ends at the first */, and whatever follows is parsed as code. So this does not do what it looks like:

Fragment — not a complete formula

/* temporarily disabled
   Average = MA( Close, 50 );  /* fifty bars */
   Plot( Average, "MA", colorBlue );
*/

The block comment ends at fifty bars */, so the Plot() line is live code and the final */ is a syntax error. To comment out a region that already contains block comments, select it and use Edit -> Line Comment in the Formula Editor, which prefixes every selected line with // and toggles back off when run again.

What a comment is for

The rule this course follows: comments explain why, not what. A comment that restates the syntax is noise, and worse, it goes stale.

Fragment — not a complete formula

// Bad: says nothing the code did not already say.
MaPeriod = 50;   // set MaPeriod to 50

// Good: says something the code cannot.
// 50 bars is roughly a quarter of a trading year. Chosen for comparability
// with the Part 6 indicator study, not because it tested well.
MaPeriod = 50;

Every strategy formula in this course also opens with a short block comment stating what it assumes — the interval it expects, whether it needs a minimum history, what it deliberately ignores. Those assumptions are invisible in the code and lethal when forgotten.

Case insensitivity

AFL identifiers are not case-sensitive. Close, close and CLOSE are the same identifier. So are maperiod and MaPeriod. The parser genuinely does not care.

This is a convenience with a sting in it. Because case carries no meaning, nothing stops you writing MaPeriod in one place and maPeriod in another, and nothing will ever tell you that you did. Any reader — including you, later — has to work out whether the two names were meant to be the same thing.

The course therefore fixes a convention and keeps to it: capitalise every word of a name, including the first. MaPeriod, SlowAverage, LiquidityFilter, HasHistory. Built-in functions and arrays are written the way the official documentation writes them: Close, MA, IIf, Plot, BarCount. The AFL editor’s auto-capitalisation feature will help you with the built-ins if you let it.

What makes a legal name

The official rules are short:

• An identifier may contain letters a–z and A–Z, the underscore _, and the digits 0–9.
• The first character must be a letter. Not a digit, and not an underscore.
• There is no length limit.

So Ma50, Slow_Average and HasEnoughHistory are all fine; 50Ma and _Temp are not. (AmiBroker’s own built-in functions such as _TRACE and _SECTION_BEGIN begin with an underscore, which is a privilege the language reserves for itself.)

Beyond legality there are three families of names to avoid.

Keywords. AFL reserves seventeen words: do, while, for, if, else, switch, break, case, continue, default, function, procedure, return, local, global, static and typeof. Five of these — switch, case, break, continue and default — only became reserved in the AmiBroker 4.91 beta cycle, and the official Knowledge Base article documenting that change exists because formulas that had been using them as ordinary variable names suddenly stopped compiling. If you inherit old AFL from somewhere and it fails to parse for no visible reason, this is a candidate.

Function names. Assigning to a name that is already a built-in function raises Error 33, “Identifier already in use”. Defining a function whose name is already a global variable raises Error 34. Both messages name the culprit, so they are easy to fix once you know what they mean.

The built-in price arrays. Open, High, Low, Close, Volume, OpenInt, Avg and their one-letter abbreviations O, H, L, C, V, OI are ordinary assignable variables, not protected constants. You can write Close = MA( Close, 5 ); and AmiBroker will accept it — and then every later line in the formula, including every built-in indicator, will silently use your smoothed series instead of the real closing price. This is occasionally a deliberate technique. Far more often it is an accident with no symptom.

✕Common mistake

The guide’s own warning lists the names not to reuse as “open, high, low, close, simple, o, c, l, h, s, a”. The last three are odd — simple, s and a appear in that one sentence and nowhere else in the documentation — but the safe reading is the simple one: never name a variable with a single letter, and never name one after a price field. a, c and x as variable names are a false economy in a language where c already means something.

Strings

String constants are written in double quotes: "Close above average". The empty string is "". Two strings can be joined with +, and a string can be joined to a number the same way, which is how the plot names in the last lesson were built.

Only five backslash escape sequences are supported: \n, \r, \t, \" and \\. Anything else raises Error 54. The practical consequence is that a Windows path inside an AFL string needs doubled backslashes — "C:\\Data\\output.csv" — because a single backslash before D is not a legal escape.

Note also that - and * are not defined for strings; only + is. "a" - "b" is Error 1, an operator/operand type mismatch.

Layout that survives contact with future you

None of this is enforced. All of it is what the course does, and what you will be glad you did when you reopen a formula in six months.

One idea per line. AFL lets you compress. Resist. A condition with four clauses is easier to read, and far easier to modify, when each clause is on its own line.

Settings at the top, in named variables. Every number that someone might reasonably want to change goes at the top of the formula with a name and, where it is not obvious, a comment explaining where the number came from. Nothing is worse to maintain than a formula with 20 appearing in four places, three of which mean the same thing and one of which does not.

Sections in the order data flows. Settings, then calculation, then output. The formulas in this part use comment banners to make the three parts visible at a glance; on a twenty-line formula that is overkill, on a hundred-line one it is the difference between readable and not.

Names that say what the thing is. MaPeriod, not p. LiquidityFilter, not f1. HasHistory, not ok. Boolean-valued arrays read best when the name is a claim that is either true or false on a given bar: Uptrend, Tradeable, HasEnoughHistory. When you later write Buy = Uptrend AND Tradeable AND NOT Quiet; the line reads as a sentence, and a line that reads as a sentence is a line whose bugs you can see.

✦Tip

Two editor features are worth turning into reflexes. Brace matching: put the caret next to any bracket and its partner is highlighted, which finds unbalanced parentheses in seconds. And bookmarks: Ctrl+F2 sets one, F2 jumps to the next. On a long formula, bookmarking the settings block and the output block saves a great deal of scrolling.

Recap

Statements end with semicolons, and may span as many lines as clarity requires; a missing semicolon is reported on the following line. Comments come in two styles and do not nest. Identifiers are case-insensitive, must start with a letter, and must not collide with the seventeen keywords, with a function name, or with the built-in price arrays — which are assignable, and will silently change what the rest of your formula sees if you assign to them.

The conventions matter more than the rules. Meaningful names, one idea per line, settings at the top, comments that explain why: none of these are checked by the parser, and all of them are what makes the difference between a formula you can maintain and a formula you rewrite.

The next lesson uses these mechanics to build expressions, and meets the precedence trap that AmiBroker’s own documentation lists as the second most common mistake in AFL.

Check your understanding

Question 1. What does this formula fragment actually do?

/* disabled for now
   Average = MA( Close, 50 );  /* fifty bars */
*/

• Comments out all three lines
• Comments out the first two lines and leaves a stray */ that is a syntax error
• Raises an error about nested comments
• Comments out only the first line

Show the answer and why

Answer: Comments out the first two lines and leaves a stray */ that is a syntax error

AFL comments do not nest. The block comment ends at the first */ it meets, which is the one after "fifty bars". The final */ on its own line is then parsed as code and fails. Use Edit -> Line Comment to disable a region that already contains block comments.

Question 2. A formula contains Close = MA( Close, 5 ); near the top. What happens to the rest of the formula?

• Nothing; Close is a protected built-in and the assignment is ignored
• A syntax error, because Close is a reserved word
• Every later reference to Close, including inside built-in functions, uses the smoothed series
• Only lines that mention Close explicitly are affected

Show the answer and why

Answer: Every later reference to Close, including inside built-in functions, uses the smoothed series

The built-in price arrays are ordinary assignable variables, not constants. Once reassigned, every subsequent calculation in the formula — including built-in indicators that read Close internally — sees the new values. It is a legitimate technique used deliberately, and a silent disaster used accidentally.

Question 3. Which of these are legal AFL identifiers? Select all that apply.

• Ma50
• Slow_Average
• 50Ma
• HasEnoughHistory

Show the answer and why

Answer: Ma50, Slow_Average, HasEnoughHistory

Letters, digits and underscores are all allowed, but the first character must be a letter, which rules out 50Ma. Legality is only the first hurdle: a legal name that collides with a keyword, a function name or a price array will still cause trouble.

Question 4. Why does the course write MaPeriod rather than maperiod, given that AFL ignores case entirely?

• Because AmiBroker runs mixed-case formulas faster
• Because case matters inside strings
• Because the parser ignoring case means nothing will ever warn you about inconsistent spelling, so the consistency has to come from you
• Because lower-case names are reserved for built-in functions

Show the answer and why

Answer: Because the parser ignoring case means nothing will ever warn you about inconsistent spelling, so the consistency has to come from you

Case-insensitivity removes a whole class of errors and, in exchange, removes a whole class of warnings. A house style is the substitute. The specific style matters far less than applying one consistently.

Check my answersClear