Arduino-Comments

Comments in Arduino (and in C/C++ programming languages) are used to annotate your code with explanations or notes that are not executed by the compiler. They are helpful for documenting your code, making it easier to understand and maintain.

Types of Comments in Arduino

1. Single-Line Comments

Single-line comments are preceded by two forward slashes (//). Everything after the // on that line is considered a comment.

cpp
// This is a single-line comment

    const int ledPin = 13; // Pin 13 has an LED connected on most Arduino boards
    
    void setup() {
      pinMode(ledPin, OUTPUT); // Initialize the digital pin as an output
    }

2. Multi-Line Comments

Multi-line comments start with /* and end with */. Everything between these symbols is considered a comment.

cpp
/*
      This is a multi-line comment.
      It can span multiple lines.
    */
    
    const int ledPin = 13; /* Pin 13 has an LED connected 
                              on most Arduino boards */
    
    void setup() {
      pinMode(ledPin, OUTPUT); /* Initialize the digital pin 
                                  as an output */
    }

Using Comments Effectively

1. Commenting Code Sections

Use comments to explain the purpose of sections of code or specific logic. This makes your code easier to read and understand.

cpp
// This section initializes the LED pin
    const int ledPin = 13; 
    
    void setup() {
      // Set the LED pin as an output
      pinMode(ledPin, OUTPUT);
    }

2. Describing Functions

Provide descriptions for functions to explain what they do, their parameters, and return values (if any).

cpp
/*
      Function: blinkLED
      Description: Blinks an LED on the specified pin at a specified interval
      Parameters: 
        - pin: the pin number where the LED is connected
        - interval: the time (in milliseconds) the LED stays on and off
    */
    void blinkLED(int pin, int interval) {
      digitalWrite(pin, HIGH); // Turn the LED on
      delay(interval);         // Wait for the specified interval
      digitalWrite(pin, LOW);  // Turn the LED off
      delay(interval);         // Wait for the specified interval
    }

3. Temporarily Disabling Code

Comments can be used to temporarily disable parts of your code during testing and debugging.

cpp
void loop() {
      // digitalWrite(ledPin, HIGH); // Turn the LED on
      delay(1000);                  // Wait for a second
      digitalWrite(ledPin, LOW);    // Turn the LED off
      delay(1000);                  // Wait for a second
    }

Example Sketch with Comments

Here’s an example of a complete Arduino sketch with comments:

cpp
// Pin 13 has an LED connected on most Arduino boards.
    const int ledPin = 13; // the number of the LED pin
    
    // The setup function runs once when you press reset or power the board.
    void setup() {
      // Initialize the digital pin as an output.
      pinMode(ledPin, OUTPUT);
    }
    
    // The loop function runs over and over again forever.
    void loop() {
      // Turn the LED on (HIGH is the voltage level).
      digitalWrite(ledPin, HIGH);   
      delay(1000); // Wait for a second
    
      // Turn the LED off by making the voltage LOW.
      digitalWrite(ledPin, LOW);    
      delay(1000); // Wait for a second
    }

Tips for Writing Good Comments

Be Clear and Concise: Write comments that are easy to understand and to the point.
Explain Why, Not What: Focus on explaining why certain decisions were made or why the code does something, rather than describing what the code does (which should be clear from the code itself).
Keep Comments Updated: Ensure that comments are updated whenever the code changes to avoid discrepancies between the code and the comments.
Avoid Redundant Comments: Don’t write comments that simply repeat what the code does. For example, i++; // Increment i by 1 is not useful.

Using comments effectively will help you and others understand and maintain your Arduino sketches more easily.

techmore.in