skip to content
Amanbolat's SWE Blog

Writing Better Code Comments

/ 3 min read

documentation, code

As a developer, I spend countless hours reading code - whether it’s exploring random GitHub repos or diving into my own projects. One thing that always catches my eye is how people write comments.

Let’s talk about comments. While they’re essential for any codebase (yes, even if your code is super clean), they need to be just as polished as the code itself. Here’s what I’ve learned about writing better comments over the years.

Ditch the redundant comments

We’ve all seen this kind of stuff:

// create db connection ❌
conn, _ := pg.NewConnection()


// create service ❌
svc, _ := service.New(conn)


// run the service ❌
go svc.Run()

These comments are just noise - they’re literally repeating what the code says. Maybe they’re leftovers from initial pseudocode or personal notes, but they’re not helping anyone. Let’s drop them.

Answer “Why?” Instead of “What?”

Sure, some complex code needs explanation in plain English. That’s fine! But don’t just describe what the code does - explain why it does it that way. Context is king.

// Bad: What-focused comment ❌
// Sleeps for 3 seconds before retrying the request
time.Sleep(3 * time.Second)


// Good: Why-focused comment ✅
// Adding delay between retries to prevent overwhelming the external API
// and avoid hitting rate limits (500 requests/minute)
time.Sleep(3 * time.Second)

Level up your TODOs

We all leave TODO comments - nothing wrong with that. They’re great reminders of what needs work. But I often see stuff like:

// TODO: improve
// TODO: maybe return error?
// TODO: it's slow

These vague TODOs are likely to stay there forever or confuse your teammates. Here’s how to write better ones:

  1. Be specific about what needs work.
  2. Add context about why it’s an issue.
  3. Include your contact info (code formatting can mess up git blame).
  4. Link to a ticket/issue.

Here’s a solid example:

// TODO(John Doe): Implement a custom logging middleware, as the one from github.com/acme/logging doesn't let us
// log request and response bodies.
// Jira ticket: TD-4456

Use tools to your advantage

Most modern IDEs have spell checkers - use them! They make comments more professional and easier to read. AI tools are also great for catching grammar issues and improving clarity.

Get Creative with ASCII Art

Sometimes a picture is worth a thousand words. When you can’t embed images in comments, ASCII art comes to the rescue. Here’s a neat example of visualizing a Docker container:

# +-----------------+
# |    Container    |
# | +-------------+ |
# | |     App     | |
# | +-------------+ |
# | |   Binaries  | |
# | +-------------+ |
# | |    Libs     | |
# | +-------------+ |
# +-----------------+
# |      Host OS    |
# +-----------------+

You can create these using tools like:

  • Asciiflow – online free tool to draw ASCII arts.
  • Monodraw – powerful ASCII art editor designed for the Mac. Not free, but cheap.

The Bottom Line

Comments are code too. Treat them with the same respect you give your actual code. Write them thinking about your teammates who’ll read them months from now. Good comments don’t just describe - they explain and provide context.

Remember: The best comment is the one that saves the next developer (probably future you) from saying “Wait… what?”