Charan Gutti

Posted on Oct 4

💬 The Art of Writing Comments: How to Talk to the Future You (and Everyone Else)

#productivity #writing #softwaredevelopment

Ever looked at your own code after six months and thought…

“Who wrote this spaghetti? Oh wait — it was me.” 😅

That’s the moment you realize:
Comments aren’t optional — they’re essential.

Whether you’re building a billion-dollar product or your first hobby app, good comments are the difference between code that ages like fine wine and code that rots like milk.

This guide isn’t about how to add slashes. It’s about learning the language of clarity — the craft of writing comments that future you (and your teammates) will thank you for.

🧠 Why Comments Exist — The True Reason

Computers understand code.
Humans understand stories.

Comments exist because our brains are not compilers — they’re storytellers.

A great comment answers three questions:

What does this do?
Why was it done this way?
What should someone be careful about if they change it?

That’s it. That’s your holy trinity.

🏷️ The 5 Essential Types of Comments

Let’s revisit these — but this time, we’ll go deeper with why they matter and how pros use them effectively.

1. 🧩 Inline Comments (Explain the “Why”)

These are like whispers inside your code — short hints that save hours of head-scratching.

let retryCount = 3; // Allow up to 3 retries before showing an error

📘 When to use:

A non-obvious constant or edge case.
A hack you’re not proud of (but must keep).

📙 When not to use:

For things that are self-explanatory.

❌ i++ // increment i
✅ i++ // move to next record in dataset

💡 Rule of thumb:

If someone could ask “Why?”, it probably deserves a comment.

2. 🧱 Block Comments (The Storytellers)

Used to describe what a chunk of code as a whole does.

"""
Handles order validation before checkout.
Includes:
- Checking product stock
- Validating promo codes
- Ensuring payment info exists
"""
def validate_order(order):
    ...

Think of block comments as your table of contents for the logic below.

🗣️ “This code isn’t confusing. It’s just unexplained.”

3. 📚 Function/Method Documentation (The Contracts)

These are formal explanations of how and why to use a function or API.
They’re critical for teamwork and reusable code.

/**
 * Sends an email to the specified user.
 * @param {string} email - Recipient email address.
 * @param {string} subject - Email subject line.
 * @param {string} body - Email content in HTML format.
 * @returns {Promise<void>}
 */
async function sendEmail(email, subject, body) { ... }

In open-source projects, these are gold.
It’s the difference between “figure it out yourself” and “I’ve got your back.”

4. 🧾 TODO, FIXME, and NOTE Comments (Your Personal Assistant)

These are action-oriented comments that help you or your teammates track pending work.

// TODO: Replace hardcoded value with env variable
// FIXME: Fails when API returns 404 — handle gracefully
// NOTE: We cache results here for 10 mins to reduce API load

💡 Pro Tip: VS Code and JetBrains IDEs automatically show TODOs in a special panel. You can literally track them as tasks.

Think of them as sticky notes inside your code — but organized.

5. 🧭 Documentation Comments (Public Knowledge)

These comments live in public-facing codebases, SDKs, and APIs.

/**
 * Calculates the SHA-256 hash of a given input.
 * @param input String to hash.
 * @return Hexadecimal representation of hash.
 */
public String hash(String input) { ... }

Professional teams often auto-generate docs from these using tools like JSDoc, Doxygen, or Sphinx.
So, every comment you write can become part of your official documentation!

🧩 Bonus: The “Invisible” Type of Comment — The Self-Documenting Code

The best comment is sometimes the one you don’t need.

Instead of writing this:

// Check if user is logged in
if (user && user.sessionActive) ...

Write this:

if (isUserLoggedIn(user)) ...

Function names, variable names, and structure can act as living comments.
That’s the real secret — make your code so readable that comments only fill in the gaps.

🧱 What Makes a Great Comment (The Principles)

🪶 1. Be Intentional

Write comments with purpose, not guilt. Don’t just comment because you “should.”

🧠 2. Add Value, Not Noise

Your comment should explain something the code cannot.

🧭 3. Keep It Honest and Updated

Outdated comments are liars. They erode trust in the entire codebase.

💬 4. Comment on Decisions, Not Descriptions

Tell why you made a choice, not what the choice is.

// Using map instead of forEach for immutability

🧘 5. Be Kind

Remember: your comment tone is part of your team’s culture.
Don’t rant, don’t roast, don’t write angry comments.
(You’re writing for humans, not for venting.)

🔍 Real-World Example:

Before (no context):

user.save();

After (thoughtful):

// Saving user immediately to ensure data is consistent across sessions
user.save();

Result: One line of comment saves 10 minutes of confusion later. Multiply that by every developer, every project, every month — that’s hundreds of hours saved.

🌍 Comments Across Languages — A Quick Tour

Language	Syntax	Example
JavaScript	`//` or `/** */`	`// Calculate total cost`
Python	`#` or `""" """`	`# Fetch latest data from API`
C / C++ / Java	`//` or `/* */`	`/* Temporary fix for bug #221 */`
Go	`//`	`// Check for nil pointer`
YAML / Bash	`#`	`# Configuration for production build`

Learn your comment syntax — it’s your brush; the code is your canvas. 🎨

⚡ Pro-Level Commenting Techniques

Use Comment Tags:

TODO → something to fix or finish
FIXME → something broken
NOTE → highlight behavior or assumption
HACK → acknowledge an ugly but necessary trick

Align Comments for Readability:

const price = 19.99;  // Base price
const tax   = 1.99;   // Added 10% tax
const total = 21.98;  // Final total

Separate Logic Sections Clearly:

// --- Authentication ---
...

// --- Database Operations ---
...

// --- Error Handling ---
...

These make code feel organized — and maintainers love you for it.

🧰 3 Practical Tips for Every Developer

Write comments as you code.
Future you won’t remember what you meant. Comment now, not later.
Read your comments out loud.
If it sounds robotic or vague, rewrite it like you’re explaining it to a teammate.
Review comments in code reviews.
Treat comments as part of code quality.
A beautiful comment deserves the same respect as a clean function.