Comments & Descriptions

Modified on July 26, 2024

Unlike most general-purpose programming languages, OtterScript is designed to be both visualized and coded. As such, most comments are not ignored by the compiler -- they actually are an important part of the script itself.

Statement Descriptions

All of the comments that precede a statement are considered to be that statement's Description. The descriptions is used as follows:

• Visual Editor Blocks - when viewing a script, either in the editor or in the web application, "block" statements use the first line of the description as the "Short Description", and the remaining lines as the "additional comments". These are displayed in different font sizes.
• Visual Editor Statements - all other statements (with the exception of Action statements) treat the description as an "additional comment", which means it's displayed with the same font style.
• Log Scoping - if a "block" statement has description, the first line will be used as the log scope.

Additional Headers

All of the comments at the beginning of an OtterScript that begin with ##AH: are considered to be Additional Headers, which essentially serve as key/value pair metadata for the script. These are not incorporated into the first statement's description.

For example, the UseVisualMode header key is used to instruct the OtterScript editor to always open in visual mode. You will see this added when switching to visual mode.

Other comments

Comments made within a statement are ignored by the compiler, which means that they will not be preserved when switching between text and visual modes in the plan editor. For example, consider the following script.

#Ensure HDars
#Creates the Hdars AppPool and Site if it doesn't exist
{
    IIS::Ensure-AppPool HDarsAppPool (
        Pipeline: Integrated, 
        Runtime: v4.0
    );
    IIS::Ensure-Site HDars (
        AppPool: HDarsAppPool,
        Path: $WebsiteRoot,
        Protocol: http,
        # bind to port 1000 on all IPs, any hostname
        Binding: *:1000:
    );
}

Log messages from the operations will be under a "Ensure HDars" log scope, and the script editor will display the "block" with a "Ensure HDars" name the following line as a comment.

However, the comment preceding the "Binding" argument will be ignored by the compiler, and lost when switching modes. That comment could be preserved by placing it before the Ensure-Site operation.

Comment Syntax

Two forms of comments are supported: single-line comments and delimited comments. Single-line comments start with the characters // or the character # and extend to the end of the source line. Delimited comments start with the characters /* and end with the characters */. Delimited comments may span multiple lines.

Comment forms will not be preserved when switching between text and visual modes.