Chapter 21: Comments

Part 1: What Are Comments?

Comments are pieces of text in your source code that are completely ignored by the compiler or interpreter. They are written for human readers, not for the machine. Their purpose is to explain, clarify, and document what your code is doing, why it’s doing it, and any important notes for anyone who might read or modify the code.

Why is this so important?

1. Explanation: They explain complex logic that might not be obvious from the code itself.

2. Intent: They communicate the programmer’s intent. The code tells you what is happening; comments can tell you why it’s happening that way.

3. Documentation: They serve as built-in documentation for functions, classes, and modules.

4. Debugging: They can be used to temporarily disable (“comment out”) sections of code to isolate bugs.

5. Collaboration: They are essential for teamwork, allowing multiple programmers to understand each other’s work.

Part 2: Types of Comments

Most programming languages support two main types of comments: single-line and multi-line. The syntax varies slightly between languages, but the concepts are universal.

1. Single-Line Comments

These comments start with a specific symbol and continue until the end of the line. Everything after the symbol is ignored.

Python:

JavaScript/Java/C/C++:

R:

2. Multi-Line Comments

These comments can span multiple lines. They have a start symbol and an end symbol. Everything in between is ignored.

Python:
Python doesn’t have a dedicated multi-line comment syntax. Instead, it conventionally uses triple-quoted strings (""") which, when not assigned to a variable, act as multi-line comments.

JavaScript/Java/C/C++:

R:
R doesn’t have a built-in multi-line comment syntax. You typically use multiple single-line comments, or use conditional blocks for large sections.

Part 3: Examples in Different Languages

Let’s see comments in action across a few different languages.

Python Example

JavaScript Example

R Example

Part 4: Best Practices for Writing Comments

Good comments are an art. Here are some guidelines to write comments that are actually helpful.

DO: Explain “Why,” Not “What”

The code itself shows what it’s doing. Comments should explain why it’s doing it that way, especially if the reason isn’t obvious.

DO: Write Comments as You Code

The best time to write a comment is when you’re writing the code. The logic is fresh in your mind. “I’ll add comments later” often becomes “I’ll never add comments.”

DO: Keep Comments Up-to-Date

When you change code, update the corresponding comments. Outdated comments are worse than no comments—they actively mislead.

DO: Use Comments to Explain Complex Algorithms

DO: Document Functions and Modules

Use docstrings (or the language’s standard documentation format) to explain what a function does, its parameters, and its return value.

DO: Use Comments for TODOs and FIXMEs

Mark areas that need future attention.

DON’T: Write Redundant Comments

Avoid stating the painfully obvious.

DON’T: Use Comments as a Substitute for Clear Code

Strive to write self-documenting code first. Use meaningful variable and function names.

DON’T: Leave Dead Code Commented Out

Commented-out code clutters the file and confuses readers. Use version control (like Git) to manage old code; don’t leave it in the source as comments.

Part 5: Language-Specific Comment Features

Python Docstrings

Python has a special feature called docstrings (documentation strings). These are multi-line strings placed right after a function, class, or module definition. They are accessible at runtime via the help() function and are used by documentation generators.

JSDoc in JavaScript

JavaScript developers often use JSDoc comments, which have a special format that tools can parse to generate documentation.

Roxygen Comments in R

R package developers use Roxygen comments, which start with #' and are used to generate documentation files.

Summary: The Comment Philosophy

• Comments are for humans, not computers. They are ignored by the compiler/interpreter.

• Single-line comments (# in Python/R, // in many others) are for brief explanations.

• Multi-line comments (""" in Python, /* */ in many others) are for longer explanations or temporarily disabling blocks of code.

• Explain the “why,” not the “what.” The code already shows what it’s doing.

• Write self-documenting code first. Use meaningful names so you need fewer comments.

• Keep comments up-to-date. Outdated comments are misleading and harmful.

• Use comments for TODOs, FIXMEs, and documentation.

• Don’t leave dead code commented out. Use version control.

Writing good comments is a sign of a considerate and professional programmer. It shows that you care not only about making the code work but also about making it understandable for everyone who comes after you—including your future self, who will be eternally grateful for those helpful notes when debugging at 3 AM.