21

## Formula 101 – #9 Comment Your Formula

We have spent a lot of time on the *syntax* of the quote formula language. But we never spend any time to talk about the *maintenance* of the formulas we have written. Since we have covered enough ground on writing formulas, it is time to address this important concept.

To improve the *readability* of our formulas and help ourselves to *maintain* the formulas, comments are used to explain to ourselves the *what* and *why* our formulas are written in a particular way.

**What are comments within the formula language?**

Comments are remarks we left within the formula that is not *processed* by NeoTicker at all. These comments are left there for ourselves to read. As a comparison, it is similar to side notes we have written on textbooks to help us learn and understand from the *content* of the textbook.

**How do we write comments?**

Whenever we write on a line with the single-quote character (`'`

) , the rest of the line is skipped by NeoTicker and whatever we have written after the single-quote will not be recognized as part of the formula.

The single-quote can start at any part of a line and NeoTicker will recognize that and skip the rest of that line when *parsing* the formula. Thus you can write your comments in many different ways and they are always recognized as comments and skipped accordingly.

**Example comments**

Since there is no formal rules on how comments are written, so I will present a few examples on how comments are written, so that you get a starting point on how it works.

First example, a *header* that identify the writer of the formula,

Second example, *full line* comments

Third example, *in-line* comments

**Summary**

Unlike classic programming textbook, I leave the topic of writing comment until after we have covered most of the topics on the formula language.

Quote formulas are, in general, short and very concise, thus the use of comment is not really necessary, until after you have to manage many formulas and formulas with multiple statements. Thus I think it more appropriate to talk about comments after we have covered the topic on multiple statements and the readers already found that working with formulas can be getting very complicated.

Remember that comments are written there to help yourself (and in some cases to help your coworkers) understand what you have written, so be as explicit as you deem necessary.

**Exercise**

Well, I cannot think of any exercise for inserting comments into your formulas, as comments are more a personal thing than writing formulas in general.

The more useful advice I can think of is to write comments that you know, when you read it again, you will be able to remind yourself the extra information about the formulas that is not obvious by just reading the code. That way, you can pick up from where you left off easier.

**Answers for Previous Exercise**

1. To make the formula more compact and readable, we can use assignment statements,

`$mymidpoint := (high (D1) + low (D1)) / 2;`

$myavg := prevDAverage (M5);

choose ($mymidpoint > $myavg, 1, $mymidpoint < $myavg, -1, 0)

2. Since I have not specified the range of each region, it is up to you to define your regions. But it is obvious that the complete range has to be within 0 to 100, because slowk can only range from 0 to 100,

`$mystoc := slowk (M5, 5, 3);`

choose ($mystoc > 80, 2, $mystoc > 60, 1, $mystoc > 40, 0, $mystoc > 20, -1, -2)

Notice that we started the comparison from the *highest* possible value and work our way down to the *lowest* possible value. When that is done in combination of the greater than comparison operator, we can effectively map the values into the classification code we wanted.

3. The trick was demonstrated within the previous article,

`playsound (`

slowk (M5, 5, 3) < 70 and slowk (1, M5, 5, 3) >= 70 and ntnow - dt (m5) < 15 / 60 / 1440,
"boing.wav")

The function *ntnow* does not return just the current date time stamped by your computer. It displays the date time that NeoTicker *thinks* it is in. Thus, if you are using Simulator Server, the ntnow function will return the date time based on the information provided by the simulation server.

**Interact:**Add a Comment | Trackback Link | Permalink

**Share:**digg | del.icio.us | Technorati | StumbleUpon