DEV Community

Charan Gutti
Charan Gutti

Posted on

💬 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:

  1. What does this do?
  2. Why was it done this way?
  3. 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
Enter fullscreen mode Exit fullscreen mode

📘 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):
    ...
Enter fullscreen mode Exit fullscreen mode

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) { ... }
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

💡 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) { ... }
Enter fullscreen mode Exit fullscreen mode

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) ...
Enter fullscreen mode Exit fullscreen mode

Write this:

if (isUserLoggedIn(user)) ...
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

🧘 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();
Enter fullscreen mode Exit fullscreen mode

After (thoughtful):

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

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

  1. Use Comment Tags:
  • TODO → something to fix or finish
  • FIXME → something broken
  • NOTE → highlight behavior or assumption
  • HACK → acknowledge an ugly but necessary trick
  1. Align Comments for Readability: 
const price = 19.99;  // Base price
const tax   = 1.99;   // Added 10% tax
const total = 21.98;  // Final total
Enter fullscreen mode Exit fullscreen mode
  1. Separate Logic Sections Clearly: 
// --- Authentication ---
...

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

// --- Error Handling ---
...
Enter fullscreen mode Exit fullscreen mode

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

🧰 3 Practical Tips for Every Developer

  1. Write comments as you code.
    Future you won’t remember what you meant. Comment now, not later.

  2. Read your comments out loud.
    If it sounds robotic or vague, rewrite it like you’re explaining it to a teammate.

  3. Review comments in code reviews.
    Treat comments as part of code quality.
    A beautiful comment deserves the same respect as a clean function.

🧙 Final Thoughts — Comment Like a Mentor

Comments aren’t just lines of text.
They’re mentorship embedded in code.

A junior dev reading your code should feel guided.
A senior dev should feel respected.
And your future self should feel… relieved.

Because someday, months from now, when you reopen that file and whisper:

“Ohhh, now I get why I did this.”

You’ll smile and say,

“Aaahaa, niceee.” 😌

Top comments (0)