Comments

Comments are essential for documenting your code and making it more readable. Rui supports both single-line and multiline comments to help you explain your code to others (and to yourself in the future).

Single-line Comments

Single-line comments start with // and continue until the end of the line:

// This is a single-line comment
suppose name = "Alice"  // Inline comment
write("Hello " + name)

// Comments can be on their own lines
// Or at the end of code lines
suppose age = 25  // Age of the person

Single-line comments are perfect for:

  • Quick explanations: Brief notes about what code does
  • Inline documentation: Comments on the same line as code
  • Temporary notes: Reminders or TODO items
  • Code disabling: Temporarily disable code without deleting it

Multiline Comments

Multiline comments start with /* and end with */:

/*
   This is a multiline comment
   that can span multiple lines
   and is completely ignored by Rui
*/

suppose age = 25

/* Another multiline comment */

write("Age: " + age)

Multiline comments are ideal for:

  • Detailed explanations: Comprehensive documentation of complex logic
  • Function documentation: Describe what functions do and their parameters
  • Code blocks: Comment out large sections of code
  • File headers: Document the purpose of entire files

Comment Best Practices

Here are some guidelines for writing effective comments:

  • Explain why, not what: Don't just repeat what the code does
  • Keep comments current: Update comments when you change code
  • Use clear language: Write comments that others can understand
  • Don't over-comment: Obvious code doesn't need comments

Good Comment Examples

// Calculate the area of a circle
define calculateArea(radius) {
    suppose pi = 3.14159
    return pi * radius * radius
}

/*
   This function processes student grades and determines
   their letter grade based on the following scale:
   A: 90-100, B: 80-89, C: 70-79, D: 60-69, F: 0-59
*/
define getLetterGrade(score) {
    if (score >= 90) {
        return "A"
    } else if (score >= 80) {
        return "B"
    } else if (score >= 70) {
        return "C"
    } else if (score >= 60) {
        return "D"
    } else {
        return "F"
    }
}

// TODO: Add support for weighted grades
// FIXME: Handle negative scores properly
suppose studentScore = 85
write("Grade: " + getLetterGrade(studentScore))

Commenting Out Code

Comments are useful for temporarily disabling code without deleting it:

suppose name = "Alice"
suppose age = 25

// Temporarily disable this line
// write("Debug: name = " + name)

write("Hello, " + name)

/*
suppose debugMode = true
if (debugMode) {
    write("Debug information:")
    write("Name: " + name)
    write("Age: " + age)
}
*/

Documentation Comments

Use comments to document functions and their parameters:

/*
   Function: calculateDistance
   Description: Calculates the distance between two points
   Parameters:
     - x1, y1: coordinates of first point
     - x2, y2: coordinates of second point
   Returns: distance as a number
*/
define calculateDistance(x1, y1, x2, y2) {
    suppose dx = x2 - x1
    suppose dy = y2 - y1
    return sqrt(dx * dx + dy * dy)
}

// Simple function with inline documentation
define greet(name) {  // name: person's name to greet
    return "Hello, " + name + "!"
}

Common Comment Patterns

Here are some common patterns for using comments:

// ===========================================
// FILE: user_management.rui
// PURPOSE: Handle user registration and login
// AUTHOR: Your Name
// DATE: 2024-01-15
// ===========================================

// Configuration constants
suppose MAX_USERS = 100
suppose MIN_PASSWORD_LENGTH = 8

/*
   User registration function
   Validates input and creates new user account
*/
define registerUser(username, password, email) {
    // Validate username length
    if (length(username) < 3) {
        write("Error: Username too short")
        return false
    }
    
    // TODO: Add email validation
    // FIXME: Check for duplicate usernames
    
    // Create user object
    suppose user = {
        username: username,
        password: password,  // Note: In real app, hash this!
        email: email,
        createdAt: getCurrentTime()
    }
    
    return true
}

// Main program
write("User Management System")
// registerUser("alice", "password123", "alice@example.com")

Comment Style Guidelines

  • Be consistent: Use the same comment style throughout your code
  • Use proper capitalization: Start comments with capital letters
  • End with periods: Complete sentences should end with periods
  • Use TODO/FIXME: Mark temporary code and known issues
  • Group related comments: Use comment blocks for related sections

Comments are a crucial part of writing maintainable code. They help you and others understand your code better, making it easier to debug, modify, and extend your programs.