C Comments

Comments are crucial elements in any programming language, including C. They allow programmers to add notes and explanations within their code without affecting the program's execution. Well-commented code is easier to understand, maintain, and debug—both for yourself and other developers who might work with your code.

Why Use Comments?

• Documentation: Explain what your code does and why
• Debugging: Temporarily disable code sections without deleting them
• Readability: Make code more understandable for yourself and others
• Planning: Outline your code structure before implementation

Types of Comments in C

C supports two different comment styles:

1. Single-line Comments

Single-line comments begin with // and continue until the end of the line. They're perfect for brief explanations.

c

// This is a single-line comment
int x = 10; // You can also place comments at the end of a line

note

Single-line comments (//) were not part of the original C language specification (C89/C90). They were officially introduced in the C99 standard. However, most modern C compilers support them regardless of the standard being used.

2. Multi-line Comments

Multi-line (or block) comments begin with /* and end with */. Everything between these delimiters is treated as a comment, even if it spans multiple lines.

c

/* This is a multi-line comment.
   It can span across multiple lines.
   Useful for longer explanations. */

int main() {
    /* This is another
       multi-line comment */
    return 0;
}

Best Practices for Using Comments

Do's:

• Explain why, not what: Good comments explain why something is done rather than what is being done (which should be clear from the code itself)
• Keep comments up-to-date: Update comments when you change code
• Use meaningful comments: Write clear, concise explanations
• Comment complex algorithms: Explain non-obvious logic or algorithms
• Document function purposes: Explain what functions do, their parameters, and return values

c

/* Calculate factorial of a number
   Parameters:
     n - The number to calculate factorial for
   Returns:
     The factorial of n, or -1 if n is negative
*/
int factorial(int n) {
    // Check for negative input
    if (n < 0) return -1;
    
    int result = 1;
    // Multiply from 1 to n
    for (int i = 1; i <= n; i++) {
        result *= i;
    }
    return result;
}

Don'ts:

• Avoid obvious comments: Don't state what's already clear from the code
• Don't overcomment: Too many comments can make code harder to read
• Don't leave commented-out code in production: It creates confusion
• Avoid inappropriate comments: Keep comments professional

Using Comments for Documentation

Many C projects use specially formatted comments for automatic documentation generation. Systems like Doxygen can parse these comments to create comprehensive API documentation.

c

/**
 * @brief Computes the square root of a number
 *
 * @param x The input value (must be non-negative)
 * @return The square root of x, or -1.0 if x is negative
 */
double my_sqrt(double x) {
    if (x < 0) return -1.0;
    // Implementation here
    return sqrt(x);
}

Using Comments for Debugging

Comments can be used to temporarily disable code sections during debugging:

c

int main() {
    printf("This line will execute\n");
    
    /*
    printf("This line won't execute\n");
    printf("Neither will this one\n");
    */
    
    return 0;
}

Many IDEs and text editors offer keyboard shortcuts to quickly comment/uncomment sections of code, making this technique even more useful.

Conclusion

Comments are a vital part of writing maintainable C code. While they don't affect program execution, well-written comments significantly improve code quality by making it more understandable and maintainable. Remember that the best code is self-documenting through clear structure and meaningful variable/function names, with comments providing additional context where needed.

Practice Exercise

Try to identify which of these comments follow good practices and which don't:

c

// Calculate area
int area = length * width;

/* This function adds two numbers
   and returns their sum */
int add(int a, int b) {
    return a + b;  // Return the sum
}

int i = 0;  // Initialize i to 0

/* ----------------------------------------
   Author: John Doe
   Date: 2023-06-15
   This function calculates a person's BMI
   using their height (in meters) and weight (in kg)
   ---------------------------------------- */
float calculate_bmi(float height, float weight) {
    return weight / (height * height);
}