Correct Way to Write Code Comments

Writing good code is not just about making it functional—it's also about making it readable and maintainable. One of the best tools for improving code readability is comments. But what is the correct way to write code comments? Let's explore best practices that can help you write meaningful, helpful comments that add value to your codebase.

Why Are Code Comments Important?

Comments are essential for several reasons:

1. Code clarity: Comments explain the "why" behind the code, not the "what". The code itself should explain the "what".

2. Collaboration: Multiple developers might work on the same codebase. Well-written comments help everyone understand the thought process behind the code.

3. Maintainability: You or someone else might revisit the code after months or years. Good comments make it easier to understand your previous logic.

However, bad or excessive comments can clutter the code, making it harder to read. Let’s go over how to avoid that.

Best Practices for Writing Code Comments 📝

1. Comment the "Why," Not the "What"

The code itself should be self-explanatory, but comments should explain why certain decisions were made. Avoid explaining what the code is doing line by line unless it’s complex or non-obvious.

// ❌ Bad Example:
// Add 1 to the counter
counter = counter + 1;


// ✅ Good Example:
// Increment the counter to track the next available user ID
counter = counter + 1;

In the second example, the comment explains why the counter is incremented, giving the context behind it.

2. Keep Comments Up to Date

Stale comments can mislead readers. If you update the code, make sure you update the comments as well. Outdated comments are worse than no comments at all!

// ❌ Bad Example:
// Check if user is active
if (user.isVerified) {
  // logic for active user
}

If the logic changes to check if the user is verified instead of active, the comment must change to reflect that. Otherwise, it becomes confusing.

3. Avoid Obvious Comments

Don’t state the obvious in your comments. If the code is simple and self-explanatory, it’s better to skip comments altogether.

// ❌ Bad Example:
// This line sets the name to 'John'
let name = 'John';

// ✅ Good Example:
// Assign default user name for guest users
let name = 'John';

The first comment is redundant because the code is self-explanatory. In the second example, the comment gives context.

4. Use Comments to Explain Complex Logic

If your code contains complex or non-obvious logic, that’s when comments become really helpful.

// We use a binary search here to improve performance
// for large datasets, which could be slow with linear search.
function binarySearch(arr, target) {
  // Binary search logic...
}

In this case, the comment explains why a particular algorithm was chosen, helping future developers understand the reasoning behind it.

5. Use Consistent Commenting Style

Consistency is key. Whether you use // for single-line comments or /* */ for block comments, stick to a pattern. Also, align the comments properly for readability.

// Fetch data from API
fetchData();

// Process the data and generate report
processData();

// Display the report to the user
displayReport();

This format is clean, organized, and easy to follow.

Types of Comments and When to Use Them

1. Single-Line Comments (//)

These are perfect for short, inline explanations or notes.

let isLoggedIn = true; // This flag checks if the user is logged in

2. Block Comments (/* */)

Use these for longer explanations, especially at the start of functions or scripts.

/* 
  This function calculates the user's total score 
  based on their completed tasks. 
*/
function calculateScore(tasks) {
  // function logic
}

A Few More Tips 🚀

• Don’t overdo it: Too many comments can be distracting. Only add comments where necessary.

• Avoid commenting out code: If code is not needed, remove it. Don’t leave large chunks of commented-out code.

• Document assumptions: If your code assumes something about input or environment, document it.

Conclusion 🎯

Writing effective comments is a skill that can dramatically improve code quality. By explaining the why, keeping comments up to date, and avoiding redundant or obvious explanations, you can ensure your comments are helpful and maintainable.

Always remember: code is read more often than it is written, so make it as clear as possible for future developers.