Why You Should Write Comments in Your Code

When you write good comments, it makes the code easier to understand and maintain. When you write comments that explain tasks, you help yourself and others work faster later. A simple line like "// Fetch user data from API and handle errors" tells exactly what the code does and why.

Many developers skip comments because they think that the code is self-explanatory. And sometimes it is. And after a few months, or when someone new joins the project, that "self-explanatory" code often becomes confusing. We are likely to forget small details. Why we implemented a certain feature as we did becomes unclear. Comments help to avoid that.

The best comments describe the task or the intention, not just what the line does. Instead of repeating the code:

// loop through array
for (let i = 0; i < items.length; i++) { ... }

You can explain the purpose:

// Group items by category for the dashboard filter
for (let i = 0; i < items.length; i++) { ... }

Anyone reading it knows why this loop exists.

Comments also help when you solve tricky problems. You spend hours debugging an edge case. When it works, write a comment so you never have to solve the same puzzle again.

Here is an example:

// Use custom timeout because the default fetch timeout is too long on slow networks in production
const response = await fetch(url, { signal: AbortSignal.timeout(15000) });

This one line saves the future you or a teammate from the same frustration.

You may think that you already know how to solve the problem you encountered. And you avoid writing comments. But believe me, you remember it only at the moment of solving it, and after some time. More time passes, and suddenly, when you encounter the same problem again, you won't be delighted by the fact that you didn't write a comment that could save you time and frustration.

A Couple of Guidelines on How to Write Comments

• Comment on the "why" and not the "what". Explain why the code does what it does.
• Keep comments short and close to the code.
• Update comments when you change code. Leaving outdated comments is worse than not having them at all.
• Use them for complex logic, workarounds, or important decisions. Simple code usually doesn't need comments. Add comments only where they add real value.
• Add a comment when something looks weird, but you know the reason. It can be one of the most important things to comment on.

Conclusion

That's it! It is a post about why you should write comments, how to write them, and the benefits they bring you. Next time you finish writing a piece of logic, pause and ask: "If I read this in a year, would I understand why it exists?" If the answer is no, add a short comment. Your future self and/or your teammates will appreciate it.

Found this helpful? Please share it with someone who also might find it helpful. Would you like more posts from me? Subscribe to the newsletter. Got questions? Send an email to commitnobug@outlook.com.