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.

Complete C Programming Guide + Compilers Collection

1. C srand() Function – Understanding Seed Initialization

https://macronepal.com/understanding-the-c-srand-function
Explains how srand() initializes the pseudo-random number generator in C by setting a seed value. Using the same seed produces the same sequence, while time(NULL) gives different results each run.

2. C rand() Function Mechanics and Limitations

https://macronepal.com/c-rand-function-mechanics-and-limitations
Explains how rand() generates pseudo-random numbers between 0 and RAND_MAX, its deterministic nature, and limitations for security use cases.

3. C log() Function

https://macronepal.com/c-log-function-2
Covers natural logarithm calculation using <math.h> and its applications.

4. Mastering Date and Time in C

https://macronepal.com/mastering-date-and-time-in-c
Explains <time.h> functions like time(), clock(), difftime(), and struct tm.

5. Mastering time_t Type in C

https://macronepal.com/mastering-the-c-time_t-type-for-time-management
Explains time representation as seconds since Unix epoch and conversion functions.

6. C exp() Function

https://macronepal.com/c-exp-function-mechanics-and-implementation
Explains exponential function exp(x) and its scientific applications.

7. C log() Function (Alternate Guide)

https://macronepal.com/c-log-function
Comparison of log() and log10() with usage examples.

8. C log10() Function

https://macronepal.com/mastering-the-log10-function-in-c
Explains base-10 logarithm for engineering and scientific applications.

9. C tan() Function

https://macronepal.com/understanding-the-c-tan-function
Explains tangent function and radian-based calculations.

10. Random Numbers in C (Secure vs Predictable)

https://macronepal.com/mastering-c-random-numbers-for-secure-and-predictable-applications
Explains difference between rand() and secure randomness methods.

11. Free Online C Compiler

https://macronepal.com/free-online-c-code-compiler-2
Browser-based compiler for testing C programs instantly.

C Functions, Arguments, Parameters & Flow

Mastering Functions in C – Complete Guide

https://macronepal.com/c/mastering-functions-in-c-a-complete-guide/
Covers function structure, modular programming, and real-world usage.

Function Arguments in C

https://macronepal.com/c-function-arguments/
Explains how arguments are passed and used in function calls.

Function Parameters in C

https://macronepal.com/c-function-parameters/
Explains defining inputs for functions and matching them with arguments.

Function Declarations in C

https://macronepal.com/c-function-declarations-syntax-rules-and-best-practices/
Covers prototypes, syntax rules, and best practices.

Function Calls in C

https://macronepal.com/understanding-function-calls-in-c-syntax-mechanics-and-best-practices/
Explains execution flow and parameter handling during function calls.

Void Functions in C

https://macronepal.com/understanding-void-functions-in-c-syntax-patterns-and-best-practices/
Explains functions that do not return values.

Return Values in C

https://macronepal.com/c-return-values-mechanics-types-and-best-practices/
Explains different return types and how functions return results.

Pass-by-Value in C

https://macronepal.com/aws/understanding-pass-by-value-in-c-mechanics-implications-and-best-practices/
Explains how copies of variables are passed into functions.

Pass-by-Reference in C

https://macronepal.com/c/understanding-pass-by-reference-in-c-pointers-semantics-and-safe-practices/
Explains using pointers to modify original variables.

C strstr() Function

https://macronepal.com/aws/c-strstr-function/
Explains substring search inside strings in C.

C Preprocessor & Macros

C Structures, Memory, Scope & Linkage

C Scope, Storage Classes & Typedef

Extra Articles

https://macronepal.com/13757-2/
https://macronepal.com/13748-2/
https://macronepal.com/13747-2/
https://macronepal.com/13746-2/
https://macronepal.com/13745-2/
https://macronepal.com/13708-2/
https://macronepal.com/13707-2/
https://macronepal.com/13702-2/

Online Compilers

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/