C Comments

Types of Comments

// This is a comment

/* This is a
   multi-line comment */

/* Calculate area
   of rectangle */

// printf("Debug");

🔹 Single-line Comments

Single-line comments in C, denoted by double slashes (//), provide a convenient way to add brief explanations or annotations to your code. Everything following // on that line is ignored by the compiler, making it perfect for short notes like int age = 25; // User's age in years. Single-line comments were introduced in C99, adopting the style from C++, and are now widely supported by modern compilers. They're ideal for explaining individual lines of code, temporarily disabling code during debugging, or adding quick reminders. Unlike multi-line comments, you can nest single-line comments safely, and they automatically terminate at the line end, reducing the risk of accidentally commenting out large code blocks.

#include <stdio.h>

int main() {
    // This is a single-line comment
    int age = 25;  // Variable to store age
    
    // Print the age
    printf("Age: %d\n", age);
    
    // Another comment
    // You can have multiple single-line comments
    
    return 0;  // End of main function
}

🔹 Multi-line Comments

Multi-line comments in C, enclosed between /* and */, allow you to add extended explanations or temporarily disable multiple lines of code. This traditional C comment style spans across multiple lines, making it ideal for detailed function descriptions, copyright notices, or explaining complex algorithms. For example, /* This function calculates the factorial of n using recursion */ can span several lines. Multi-line comments cannot be nested in standard C, so /* outer /* inner */ */ will end at the first */, potentially causing compilation errors. They're useful for commenting out large code sections during debugging, writing detailed documentation headers, or providing extensive explanations that require multiple sentences to convey the full context and reasoning.

#include <stdio.h>

/*
 * This is a multi-line comment
 * It can span several lines
 * and is useful for longer explanations
 */

int main() {
    /* 
       This program demonstrates
       the use of variables and
       basic output in C
    */
    
    int number = 42;
    
    /* Print the number */
    printf("The answer is: %d\n", number);
    
    /* Multi-line comment can also be inline */ int x = 10;
    
    return 0;
}

🔹 Good Commenting Practices

Effective commenting practices focus on explaining why code exists and what it accomplishes, not merely describing what's syntactically obvious from reading the code. Good comments clarify the programmer's intent, document assumptions, explain complex algorithms, warn about pitfalls, and provide context that isn't evident from the code alone. Avoid redundant comments like i++; // increment i that state the obvious. Instead, explain business logic, edge cases, or reasoning: // Skip first element as it's the header row. Write comments before implementing complex sections to clarify your approach. Update comments when changing code to prevent misleading information. Use TODO and FIXME markers for future work. Well-commented code serves as documentation that helps others (including future you) understand and maintain the program effectively.

#include <stdio.h>

/*
 * Program: Simple Calculator
 * Author: Your Name
 * Date: Today's Date
 * Purpose: Demonstrate basic arithmetic operations
 */

int main() {
    // Declare variables for calculation
    int num1 = 10;
    int num2 = 5;
    int result;
    
    // Perform addition
    result = num1 + num2;
    printf("Addition: %d + %d = %d\n", num1, num2, result);
    
    // Perform subtraction
    result = num1 - num2;
    printf("Subtraction: %d - %d = %d\n", num1, num2, result);
    
    // Perform multiplication
    result = num1 * num2;
    printf("Multiplication: %d * %d = %d\n", num1, num2, result);
    
    // TODO: Add division operation later
    
    return 0; // Program executed successfully
}

🔹 Commenting Tips

Following commenting tips ensures your code documentation enhances rather than clutters your codebase, making it more maintainable and professional. Be concise but informative, avoiding essays when a sentence suffices. Keep comments synchronized with code changes to prevent misleading documentation. Use consistent formatting and style throughout your project. Place comments near the code they describe for easy reference. Avoid obvious comments that simply restate what the code clearly shows. Focus on explaining complex logic, algorithms, workarounds, and business rules. Use function header comments to describe parameters, return values, and side effects. Consider using documentation generation tools like Doxygen for formal API documentation. Remember that well-written, self-documenting code with meaningful variable and function names reduces the need for excessive comments.

#include <stdio.h>

int main() {
    // GOOD: Explain WHY, not just WHAT
    int temperature = 98; // Normal human body temperature in Fahrenheit
    
    // BAD: Obvious comment
    // int x = 5; // Assign 5 to x
    
    // GOOD: Explain complex logic
    if (temperature > 100.4) {
        // Fever threshold according to medical standards
        printf("You have a fever!\n");
    }
    
    // GOOD: Explain business rules
    float discount = 0.10; // 10% discount for senior citizens
    
    // GOOD: Mark incomplete code
    // TODO: Add input validation
    // FIXME: Handle negative temperatures
    
    /* 
     * GOOD: Document function purpose
     * This section calculates the final price
     * after applying discounts and taxes
     */
    
    return 0;
}