COMMENTS IN PROGRAMMING

Table of Contents

What Are Comments?

Comments are human-readable text embedded in source code that are ignored by compilers and interpreters. They serve as documentation to explain what the code does, why it exists, and how to use it.

Types of Comments

1. Single-line Comments

Start with specific markers and continue to the end of the line:

# This is a Python comment
x = 10  # inline comment

// This is a JavaScript comment
let y = 20; // inline comment

// C, C++, Java, C# also use //
int z = 30; // inline comment

2. Multi-line Comments

Span across multiple lines:

"""
This is a multi-line comment
in Python (docstring)
"""

/*
* This is a multi-line comment
* in JavaScript, C, Java, etc.
*/

<!-- HTML comment -->

3. Documentation Comments (Docstrings/Doccomments)

Special comments used to generate documentation:

def calculate_area(radius):
"""
Calculate the area of a circle.
Args:
radius (float): The radius of the circle
Returns:
float: The area of the circle
"""
return 3.14159 * radius ** 2

/**
* Calculates the area of a circle.
* 
* @param radius The radius of the circle
* @return The area of the circle
*/
public double calculateArea(double radius) {
return Math.PI * radius * radius;
}

Why Use Comments?

✅ Good Reasons

Explain intent - Why something is done, not just what
Document complex algorithms - Clarify non-obvious logic
API documentation - Explain parameters, returns, and usage
TODOs and warnings - Mark incomplete work or potential issues
License information - Copyright and usage rights
Debugging - Temporarily disable code

❌ Bad Reasons

Explaining obvious code (redundant comments)
As a substitute for clean, self-documenting code
Outdated comments that mislead readers

Best Practices

Do:

# Calculate compound interest with monthly compounding
# Formula: A = P(1 + r/n)^(nt)
def compound_interest(principal, rate, time, n=12):
return principal * (1 + rate/n) ** (n * time)

Don't:

# Add a and b
def add(a, b):
return a + b  # return sum

Language-Specific Comment Syntax

Language	Single-line	Multi-line
Python	`#`	`"""` `"""` or `'''` `'''`
JavaScript/Java/C/C++	`//`	`/* */`
HTML/XML	N/A	`<!-- -->`
SQL	`--`	`/* */`
Ruby	`#`	`=begin` `=end`
PHP	`//`, `#`	`/* */`
CSS	N/A	`/* */`

Special Comment Types

TODO Comments

# TODO: Add error handling for negative values
# FIXME: This function is O(n²), needs optimization
# NOTE: This assumes Python 3.8+

Conditional Comments (language-specific)

#ifdef DEBUG
printf("Debug: x = %d\n", x);
#endif

The "Comment vs. Self-Documenting Code" Debate

Modern best practices emphasize writing self-documenting code with:

Meaningful variable names (total_price not tp)
Small, focused functions
Clear control structures

Comments should explain why, not what. The code itself should explain what it does.

Key Takeaway: Comments are essential for maintainable code, but they require discipline to keep accurate and meaningful. Good comments explain rationale, not mechanics, and they evolve with the code they document.

Building Blocks of C: A Complete Guide to Functions
Explains how functions work in C programming, including function declaration, definition, parameters, return values, and how functions help organize reusable code.
https://macronepal.com/bash/building-blocks-of-c-a-complete-guide-to-functions/

The Heart of Text Processing: A Complete Guide to Strings in C
Explains how strings are used in C, covering character arrays, string handling functions, and common techniques for text processing tasks.
https://macronepal.com/bash/the-heart-of-text-processing-a-complete-guide-to-strings-in-c-2/

The Cornerstone of Data Organization: A Complete Guide to Arrays in C
Describes how arrays store multiple values in C, including indexing, initialization, and using arrays to manage structured data efficiently.
https://macronepal.com/bash/the-cornerstone-of-data-organization-a-complete-guide-to-arrays-in-c/

Guaranteed Execution: A Complete Guide to the Do-While Loop in C
Explains the do-while loop structure in C, highlighting how it ensures code runs at least once before checking the loop condition.
https://macronepal.com/bash/guaranteed-execution-a-complete-guide-to-the-do-while-loop-in-c/

Mastering Iteration: A Complete Guide to the For Loop in C
Explains how the for loop works in C, including initialization, condition checking, and increment steps for repeated execution of code blocks.
https://macronepal.com/bash/mastering-iteration-a-complete-guide-to-the-for-loop-in-c/

Mastering Iteration: A Complete Guide to While Loops in C
Explains the while loop structure in C, focusing on condition-based repetition and proper loop control techniques.
https://macronepal.com/bash/mastering-iteration-a-complete-guide-to-while-loops-in-c/

Beyond If-Else: A Complete Guide to Switch Case in C
Explains how switch-case statements work in C programming, enabling efficient handling of multiple conditional branches.
https://macronepal.com/bash/beyond-if-else-a-complete-guide-to-switch-case-in-c/

Mastering the Fundamentals: A Complete Guide to Arithmetic Operations in C
Explains how arithmetic operators such as addition, subtraction, multiplication, and division work in C, along with operator precedence and usage examples.
https://macronepal.com/bash/mastering-the-fundamentals-a-complete-guide-to-arithmetic-operations-in-c/

Foundation of C Programming: A Complete Guide to Basic Input Output
Explains how input and output functions like printf and scanf work in C, forming the foundation for interacting with users and displaying program results.
https://macronepal.com/bash/foundation-of-c-programming-a-complete-guide-to-basic-input-output/