Reference: Comment

☰ Hide Sidebar

TOKEN COMMENT

ALIAS //

The Comment Delimiter is used to add explanatory notes to ProtoLang code that are ignored during execution. Comments help document what the code does, explain complex logic, or temporarily disable code. Everything from the comment delimiter to the end of the line is a treated comment and has no effect on program execution.

Syntax

The short syntax structure uses the // symbol:

// This is a comment

The long syntax structure uses the word COMMENT:

COMMENT This is a comment

How Comments Work

Comments provide a way to include non-executable text in your code:

The comment delimiter (// or COMMENT) marks the start of a comment
Everything from the delimiter to the end of that line is ignored
Comments can appear on their own line or at the end of a code line
The parser completely skips comment content during execution

Example: Basic Comment

// This is a comment that explains the next line
NEW INT x = 5
PRINTLN x // This comment is at the end of a line
// Displays: 5

Single-Line Comments

Example: Comment on Its Own Line

// Initialize the counter variable
NEW INT counter = 0
// Print the counter value
PRINTLN counter
// Displays: 0

Example: Multiple Comment Lines

// This program demonstrates counting
// It counts from 1 to 5
// Each number is displayed on a new line
NEW INT i = 1
WHILE i <= 5
    PRINTLN i
    SET i = i + 1
END WHILE

Example: Comment Before Code Block

NEW INT age = 25
// Check if user is an adult
IF age >= 18
    PRINTLN "Adult"
ELSE
    PRINTLN "Minor"
END IF

End-of-Line Comments

Example: Comments After Statements

NEW INT x = 10 // Initialize x to 10
NEW INT y = 20 // Initialize y to 20
NEW INT sum = x + y // Calculate the sum
PRINTLN sum // Display the result
// Displays: 30

Example: Explaining Variable Purpose

NEW INT playerHealth = 100 // Maximum health
NEW INT playerScore = 0 // Starting score
NEW STR playerName = "Hero" // Default player name
NEW BOOL isAlive = TRUE // Player status

Example: Documenting Calculations

NEW FLOAT price = 100.0 // Base price
NEW FLOAT taxRate = 0.08 // 8% tax rate
NEW FLOAT tax = price * taxRate // Calculate tax
NEW FLOAT total = price + tax // Add tax to price
PRINTLN total // Displays: 108.0

Documenting Code Logic

Example: Explaining Conditionals

NEW INT score = 85
// Determine letter grade based on score
IF score >= 90
    PRINTLN "A" // Excellent
ELIF score >= 80
    PRINTLN "B" // Good
ELIF score >= 70
    PRINTLN "C" // Average
ELSE
    PRINTLN "F" // Failing
END IF

Example: Explaining Loop Purpose

NEW INT i = 1
NEW INT sum = 0
// Calculate sum of numbers from 1 to 10
WHILE i <= 10
    SET sum = sum + i // Add current number to sum
    SET i = i + 1 // Move to next number
END WHILE
PRINTLN "Sum: " .. sum

Example: Step-by-Step Documentation

// Temperature conversion program
NEW FLOAT celsius = 25.0 // Temperature in Celsius
// Formula: F = (C × 9/5) + 32
NEW FLOAT fahrenheit = ( celsius * 9.0 / 5.0 ) + 32.0
PRINTLN celsius .. "C = " .. fahrenheit .. "F"
// Displays: 25.0C = 77.0F

Commenting Out Code

Comments can temporarily disable code without deleting it.

Example: Disabling a Statement

NEW INT x = 10
PRINTLN x
// PRINTLN "This line is disabled"
PRINTLN "This line executes"
// Only the uncommented lines run

Example: Testing Alternatives

NEW INT value = 5
// SET value = 10 // Try this value
// SET value = 15 // Or this value
SET value = 20 // Currently using this value
PRINTLN value // Displays: 20

Example: Debugging

NEW INT x = 1
WHILE x <= 3
    PRINTLN "x = " .. x
    // PRINTLN "Debug: before increment" // Debug line disabled
    SET x = x + 1
    // PRINTLN "Debug: after increment" // Debug line disabled
END WHILE

Example: Comparing Implementations

NEW INT count = 5
// Old implementation:
// WHILE count > 0
//     PRINTLN count
//     SET count = count - 1
// END WHILE

// New implementation:
NEW INT i = 1
WHILE i <= count
    PRINTLN i
    SET i = i + 1
END WHILE

Section Headers and Dividers

Example: Section Headers

// ========================================
// INITIALIZATION
// ========================================
NEW INT playerScore = 0
NEW INT playerLives = 3

// ========================================
// GAME LOOP
// ========================================
WHILE playerLives > 0
    SET playerScore = playerScore + 10
    SET playerLives = playerLives - 1
END WHILE

// ========================================
// DISPLAY RESULTS
// ========================================
PRINTLN "Final Score: " .. playerScore

Example: Organizing Code Sections

// --- Variable Declarations ---
NEW FLOAT width = 10.5
NEW FLOAT height = 7.5

// --- Calculations ---
NEW FLOAT area = width * height
NEW FLOAT perimeter = ( width + height ) * 2.0

// --- Output ---
PRINTLN "Area: " .. area
PRINTLN "Perimeter: " .. perimeter

Example: Function-Style Comments

// ==================================================
// Calculate factorial of a number
// Input: n (positive integer)
// Output: factorial value
// ==================================================
NEW INT n = 5
NEW INT factorial = 1
NEW INT i = 1
WHILE i <= n
    SET factorial = factorial * i
    SET i = i + 1
END WHILE
PRINTLN "Factorial of " .. n .. " is " .. factorial

Explaining Complex Logic

Example: Algorithm Explanation

// Fibonacci sequence generator
// Each number is the sum of the previous two numbers
NEW INT current = 1
NEW INT previous = 0
NEW INT temp = 0
NEW INT count = 1
WHILE count <= 10
    PRINTLN current
    SET temp = current // Save current value
    SET current = current + previous // Calculate next number
    SET previous = temp // Update previous for next iteration
    SET count = count + 1
END WHILE

Example: Nested Logic Documentation

NEW INT num = 1
// Check each number from 1 to 20
WHILE num <= 20
    // Check if divisible by both 3 and 5
    IF num % 3 == 0
        IF num % 5 == 0
            PRINTLN num .. " - FizzBuzz" // Divisible by both
        ELSE
            PRINTLN num .. " - Fizz" // Divisible by 3 only
        END IF
    ELIF num % 5 == 0
        PRINTLN num .. " - Buzz" // Divisible by 5 only
    ELSE
        PRINTLN num // Not divisible by 3 or 5
    END IF
    SET num = num + 1
END WHILE

Example: Assumptions and Constraints

// Password validation
// Assumes: password is between 8-20 characters
// Requires: at least one number
NEW STR password = "SecurePass123"
NEW INT minLength = 8
NEW INT maxLength = 20
// Note: Actual character counting not implemented in this example
PRINTLN "Password: " .. password

TODO and Reminder Comments

Example: TODO Markers

NEW INT score = 0
// TODO: Add input validation
// TODO: Implement high score tracking
// TODO: Add difficulty levels
PRINTLN "Score: " .. score

Example: FIXME Markers

NEW INT value = 10
SET value = value * 2
// FIXME: This calculation is incorrect for negative values
PRINTLN value

Example: NOTE Markers

NEW FLOAT temperature = 25.0
// NOTE: Temperature is in Celsius
// NOTE: Conversion formula may need adjustment for extreme values
NEW FLOAT fahrenheit = ( temperature * 9.0 / 5.0 ) + 32.0
PRINTLN fahrenheit .. "F"

Comments in Different Contexts

Example: Comments in Conditionals

NEW INT age = 20
NEW BOOL hasLicense = TRUE
// Check driving eligibility
IF age >= 18 // Must be 18 or older
    IF hasLicense // Must have valid license
        PRINTLN "Can drive"
    ELSE
        PRINTLN "Need license" // Age ok, but no license
    END IF
ELSE
    PRINTLN "Too young" // Under 18
END IF

Example: Comments in Loops

NEW INT i = 1
// Print odd numbers from 1 to 10
WHILE i <= 10
    IF i % 2 != 0 // Check if odd
        PRINTLN i
    END IF
    SET i = i + 1 // Increment counter
END WHILE
// Loop complete

Example: Comments with Nested Structures

// Multiplication table generator
NEW INT row = 1
NEW INT col = 1
WHILE row <= 3 // Outer loop: rows
    WHILE col <= 3 // Inner loop: columns
        PRINT row * col .. " "
        SET col = col + 1
    END WHILE
    PRINTLN "" // New line after each row
    SET row = row + 1
END WHILE

Practical Documentation Examples

Example: Program Header

// ==================================================
// Program: Temperature Converter
// Purpose: Convert Celsius to Fahrenheit
// Date: January 28, 2026
// ==================================================
NEW FLOAT celsius = 100.0
NEW FLOAT fahrenheit = ( celsius * 9.0 / 5.0 ) + 32.0
PRINTLN celsius .. "C = " .. fahrenheit .. "F"

Example: Variable Documentation

// Configuration variables
NEW INT maxAttempts = 3 // Maximum login attempts allowed
NEW INT timeout = 30 // Timeout in seconds
NEW BOOL debugMode = FALSE // Enable debug output

// User data
NEW STR username = "admin" // Current username
NEW INT loginCount = 0 // Number of login attempts

Example: Business Logic Documentation

// Calculate employee bonus
// Bonus = 10% of sales if sales > 10000
// Bonus = 5% of sales if sales > 5000
// No bonus otherwise
NEW FLOAT sales = 12000.0
NEW FLOAT bonus = 0.0
IF sales > 10000.0
    SET bonus = sales * 0.10 // 10% bonus
ELIF sales > 5000.0
    SET bonus = sales * 0.05 // 5% bonus
END IF
PRINTLN "Bonus: $" .. bonus

Example: Data Processing Pipeline

// Step 1: Initialize data
NEW INT total = 0
NEW INT count = 0

// Step 2: Process items
NEW INT i = 1
WHILE i <= 5
    SET total = total + ( i * 10 )
    SET count = count + 1
    SET i = i + 1
END WHILE

// Step 3: Calculate average
NEW INT average = total / count

// Step 4: Display results
PRINTLN "Total: " .. total
PRINTLN "Count: " .. count
PRINTLN "Average: " .. average

Comment Placement Best Practices

Example: Comment Above Code

// Calculate circle area
NEW FLOAT radius = 5.0
NEW FLOAT area = 3.14159 * radius * radius
PRINTLN "Area: " .. area

Example: Comment Beside Code

NEW INT x = 10 // Starting value
NEW INT y = 20 // Ending value
NEW INT diff = y - x // Calculate difference
PRINTLN diff // Displays: 10

Example: Mixed Placement

// Initialize shopping cart
NEW INT itemCount = 0 // Number of items
NEW FLOAT cartTotal = 0.0 // Total price

// Add items to cart
SET itemCount = itemCount + 1 // Add first item
SET cartTotal = cartTotal + 29.99
SET itemCount = itemCount + 1 // Add second item
SET cartTotal = cartTotal + 49.99

// Display cart summary
PRINTLN "Items: " .. itemCount
PRINTLN "Total: $" .. cartTotal

Comments Don't Affect Execution

Example: Comments Are Ignored

NEW INT x = 5
// SET x = 10 // This line doesn't execute
PRINTLN x // Displays: 5 (not 10)

Example: Multiple Commented Lines

NEW INT value = 100
// NEW INT value = 200
// NEW INT value = 300
// NEW INT value = 400
PRINTLN value // Displays: 100

Example: Comments in Output

PRINTLN "This prints"
// PRINTLN "This does not print"
PRINTLN "This also prints"
// Displays: This prints, This also prints

Important Notes

Comments start with // or COMMENT and continue to the end of the line.
Comments are completely ignored during program execution.
Comments can appear on their own line or after code on the same line.
There are no multi-line comments in ProtoLang; use multiple single-line comments instead.
Comments are case-insensitive like other ProtoLang tokens.
Comments can contain any text, including ProtoLang code that won't execute.
Use comments to explain why code does something, not just what it does.
Good comments improve code readability and maintainability.

Common Errors

Error: Using Wrong Comment Symbol

# This is not a valid comment // Syntax error! ProtoLang uses //
NEW INT x = 5

/* This is not valid */ // Syntax error! ProtoLang doesn't support /* */
NEW INT y = 10

// Correct: Use // for comments
// This is a valid comment
NEW INT z = 15

Error: Expecting Multi-Line Comments

/* This comment
   spans multiple lines
   but ProtoLang doesn't support this */ // Syntax error!

// Correct: Use separate // for each line
// This comment
// spans multiple lines
// using single-line comment syntax

Error: Statement Terminator in Comment

// This comment doesn't need a semicolon // The semicolon is part of the comment text
NEW INT x = 5 // This semicolon terminates the NEW statement
PRINTLN x

Error: Thinking Comments Execute

NEW INT x = 5
// SET x = 10 // This line is commented out
PRINTLN x // Displays: 5 (not 10)
// The SET command inside the comment didn't execute

Error: Forgetting Comment Delimiter

NEW INT x = 5
This is supposed to be a comment // Syntax error! Missing //
PRINTLN x

// Correct: Start comment with //
NEW INT y = 10
// This is a proper comment
PRINTLN y

Error: Comment Breaking Code Line

NEW INT x = // comment here 5 // Syntax error! Comment breaks the statement
PRINTLN x

// Correct: Comment at end of line or separate line
NEW INT y = 5 // comment here
PRINTLN y

Error: Nested Comments

// This is a comment // with another comment // inside
// The above works fine because everything after first // is ignored
NEW INT x = 5
PRINTLN x

Error: Using String Comment

NEW STR message = // "Hello" // Syntax error! Comment can't be part of value
PRINTLN message

// Correct: Don't use comment in the middle of statement
NEW STR message = "Hello" // Comment goes here
PRINTLN message

Error: Commenting Out Only Part of Statement

NEW INT x = 5
SET x = // 10 // Syntax error! Rest of line is comment, statement incomplete
PRINTLN x

// Correct: Comment entire statement or none of it
// SET x = 10 // Entire line commented
SET x = 15 // Or don't comment it
PRINTLN x

Error: Expecting Comment to Span Lines

// This comment does not
continue on this line // Wrong expectation!
NEW INT x = 5 // This line tries to execute

// Correct: Start each comment line with //
// This comment is on one line
// This is a separate comment line
NEW INT y = 10

Error: Comment in String Literal

NEW STR message = "Hello // World"
PRINTLN message // Displays: Hello // World
// The // inside the string is just text, not a comment

Error: Using Comment Delimiter Incorrectly

NEW INT x = 5 //; // The semicolon is part of the comment!
PRINTLN x // Syntax error on previous line

// Correct: Semicolon before comment
NEW INT y = 10 // Comment after semicolon
PRINTLN y

Error: Thinking Commented Code Still Affects Scope

// NEW INT x = 5 // This variable is NOT created
PRINTLN x // Runtime error! x doesn't exist

// Correct: Uncomment the declaration
NEW INT x = 5 // Now x is created
PRINTLN x

Error: Confusing Comment Position

NEW // Initialize variable
INT x = 5 // Syntax error! Comment breaks statement

// Correct: Comment before or after, not in middle
// Initialize variable
NEW INT x = 5
// Or: NEW INT x = 5 // Initialize variable

Error: Using Comments in Expressions

NEW INT result = 5 + // add this 3 // Syntax error! Comment breaks expression
PRINTLN result

// Correct: Comment after complete expression
NEW INT result = 5 + 3 // add these numbers
PRINTLN result