A few tips on writing better comments for the code

One thing I love doing is reading programming code, whether it’s a random open-source project I stumbled upon on GitHub or a piece of software I’m working on.

Something that bugs me in code is comments. Don’t get me wrong, comments are crucial to any codebase, no matter how clean your code is. But that means comments should be just as clean and concise as the code itself.

Here are a few tips I try to follow to write better comments for my code.

Ditch the redundant comments

In almost every project, I see comments like this:

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

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

// run the service
go svc.Run()

These comments are totally unnecessary – they’re just repeating what the code already says. Maybe you wrote some pseudocode first and then implemented the feature, or left some notes for yourself. Either way, these kinds of comments aren’t doing anyone any favors. Why? Well:

• pg.NewConnection() might do more than just create a new connection. So this comment could actually mislead other developers.
• The code under the “create service” comment will probably grow, and the comment will end up being outdated.
• And that last one – why bother adding a comment for code that’s already crystal clear?

Focus on “Why?” not “What?”

Now, you might argue that some code is really complex and needs explaining in plain English. Fair enough, and that’s actually good practice. But your comment should also give some context by explaining why it was done this way and not another.

Write better TODOs

A lot of us developers tend to leave TODO comments, which is fine – they help you quickly understand what needs improving when you come back to that code. But people often leave super short TODO comments without much context, like:

// TODO: improve

// TODO: maybe return error?

// TODO: it's slow

Comments like these might stay as TODOs forever or confuse other team members who want to work on that part of the project. The person who wrote the comment might leave the company or switch teams, and then no one knows what exactly needs doing or why.

So, I suggest putting a bit more effort into writing good TODO comments. How?

• Spell out exactly what needs improving, or explain the issue if you don’t have a solution yet.
• Give more context if you can. Explain why it’s an issue or what the alternatives are.
• Add your name or email address, as the code might get reformatted and it’ll be hard to track down who left the comment using git history.
• Create a ticket and link it in the comment.

Here’s an example of a solid TODO comment:

// 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.
// Ticket: TD-4456

Use spell checkers or AI

People will find it way easier to read comments if there aren’t any typos or errors. These days, pretty much every IDE has built-in spell checkers – use them! AI tools are also great for proofreading comments and fixing style issues.

Wrap-up

Treat your comments with the same care as your code. Give more context in your comments, and write them not just for yourself, but for your teammates too!