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

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

❌ Bad Reasons

1. Explaining obvious code (redundant comments)
2. As a substitute for clean, self-documenting code
3. 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.