When Should You Comment Embedded Code? Best Practices to Avoid Over‑ or Under‑Commenting

Why Comments Matter in Embedded Code

In embedded software development, comments serve as supplemental documentation that clarifies complex algorithms, special implementation tricks, and critical logic nodes, helping readers quickly grasp intent and reducing maintenance effort.

Risks of Over‑Commenting

Too many comments increase maintenance cost and can become outdated, misleading developers when the code changes. The article shows two typical over‑commenting cases.

// Define a variable to store the result
int sum = 0;
// Iterate over the array and sum all elements
for (int i = 0; i < arraySize; i++) {
    // Add the current element to sum
    sum += array[i];
}
// Return the computed sum
return sum;

The logic is straightforward, yet each line is redundantly explained.

void UART_Init(void) {
    // Set baud rate to 9600
    UART_SetBaudRate(9600);
    // Set data bits to 8
    UART_SetDataBits(8);
    // Set stop bits to 1
    UART_SetStopBits(1);
    // Enable UART communication
    UART_Enable();
}

Here the comments merely repeat what the function calls already convey.

Best‑Practice Recommendations

Comment Complex Algorithms and Logic : Explain the core idea, key steps, and possible optimizations for mathematically intensive or data‑processing code.

// Use Kalman filter for sensor data fusion
// kalmanFilter() receives the current measurement and the previous prediction
// Returns the updated prediction
float kalmanFilter(float measurement, float previousPrediction) {
    // ... algorithm implementation details ...
    return updatedPrediction;
}

Explain Special Implementations and Tricks : Document why a particular technique is used.

// Pack two 8‑bit unsigned values into one 16‑bit integer
uint16_t packValues(uint8_t value1, uint8_t value2) {
    return (value1 << 8) | value2;
}

Document Interfaces and Function Calls : State parameters, return values, possible errors, and usage notes.

// Send a single byte over UART
// data: byte to transmit
// Returns success flag
int UART_SendByte(uint8_t data) {
    // ... transmission implementation ...
    return success;
}

Avoid Commenting Trivial Code : Let clear code speak for itself; excessive comments only add noise.

Core Principles for Writing Comments

Accuracy : Comments must reflect the actual behavior of the code.

// Correct comment
// This function computes the sum of two integers
int add(int a, int b) { return a + b; }
// Incorrect comment
// This function performs a complex mathematical operation

Conciseness : Keep comments brief and avoid redundant phrasing.

// Verbose comment
// This function calculates the sum of two numbers; it receives two integer parameters and returns their sum.
int sum(int x, int y) { return x + y; }
// Concise comment
// Compute the sum of two integers

Consistency : Use a uniform style throughout the codebase.

// Consistent style
// Initialize UART parameters
void uart_init_params(void) {
    // Set baud rate
    uart_set_baudrate(9600);
    // Set data bits
    uart_set_databits(8);
}
// Inconsistent style
// Initialize UART
void initialize_uart(void) {
    // baudrate: 9600
    set_baud(9600);
}

Maintainability : Update comments whenever the associated code changes.

// Old code and comment
// Compute product of two numbers
int multiply(int a, int b) { return a * b; }
// Updated code and comment
// Compute product with overflow check
int multiply_safe(int a, int b) {
    if (a > INT_MAX / b || b > INT_MAX / a) {
        // Handle overflow
    }
    return a * b;
}

Additional Writing Tips

Use Natural Language : Write comments in clear, readable prose.

// Perform bubble sort in ascending order
void bubble_sort(int arr[], int size) {
    // ... sorting algorithm implementation ...
}

Explain Design Decisions : Clarify the rationale behind non‑obvious choices.

// Fast multiplication using bit operations to reduce compute time
int fast_multiply(int a, int b) {
    int result = 0;
    while (b > 0) {
        if (b & 1) result += a;
        a <<= 1;
        b >>= 1;
    }
    return result;
}

Document Complex Logic : Provide detailed explanations for state machines or intricate control flow.

// State machine transition logic
void state_machine(int input) {
    static int currentState = STATE_IDLE;
    switch (currentState) {
        case STATE_IDLE:
            if (input == TRIGGER_EVENT) {
                currentState = STATE_ACTIVE;
                // Initialize resources for active state
                initialize_resources();
            }
            break;
        case STATE_ACTIVE:
            // Process input in active state
            process_input(input);
            if (input == EXIT_EVENT) {
                currentState = STATE_IDLE;
                // Clean up resources used by active state
                cleanup_resources();
            }
            break;
        // ... other states ...
    }
}

Avoid Redundant Comments : Do not repeat what the code already expresses.

// Redundant comment
int max_value(int a, int b) {
    int result = (a > b) ? a : b; // Return the larger of a and b
    return result;
}
// Proper comment explaining extra constraint
int max_value_non_negative(int a, int b) {
    // Ensure a and b are non‑negative, then return the larger value
    if (a < 0 || b < 0) {
        // Handle error or default case
    }
    int result = (a > b) ? a : b;
    return result;
}

Conclusion

In embedded programming, comments are a double‑edged sword: well‑crafted annotations improve readability and maintainability, while excessive or stale comments increase overhead and confusion. Striking the right balance by following accuracy, brevity, consistency, and timely updates ensures that comments truly serve as useful documentation.