Mastering Comments in Programming: Types and Best Practices for Writing Comments (For Professional Developers)

What Are Comments?

In programming, comments are notes written in the code that the computer ignores when it runs the program. They’re used to explain what the code is doing so humans can easily understand it. This is super helpful when multiple people are working on the same project. It’s like leaving a note for your future self or for someone else who’s reviewing the code.

Why use comments?

• To explain your code: Writing down what each section of your code does will help others (and even yourself) understand it later.
• To disable code: You can “turn off” certain parts of your code temporarily without deleting it, which is helpful for testing.
• To keep track of tasks: Comments can act as a to-do list for things that still need to be done in your program.

Types of Comments in JavaScript

1. Single-Line Comments

A single-line comment in JavaScript starts with two slashes //. Anything after those two slashes is ignored by the computer when it runs the code. Use this type of comment when you need to explain a small piece of code.

// This is a single-line comment
console.log('Hello World'); // This is another comment next to a line of code

In the example above, both comments will be skipped when the code is run. They're just there for humans to understand.

2. Multi-Line Comments

When you need to write a longer comment that takes up more than one line, you use multi-line comments. These start with /* and end with */. Everything between those symbols is ignored by the computer.

/*
  This is a multi-line comment.
  You can add explanations here that take up more than one line.
  It’s helpful for explaining larger chunks of code.
*/

Multi-line comments are great when you want to explain something in detail or write longer notes to yourself or your team.

Why Comments Are Important

• Collaboration: If you’re working on a project with others, comments help them understand your thought process and what your code is doing.
• Remembering: Sometimes, you might come back to a project months later. Comments will remind you what each part of the code is supposed to do.
• Testing: Comments are also useful for turning off certain parts of your code when you want to test something out. Instead of deleting the code, you just “comment it out” and bring it back later if needed.

---

Best Practices for Writing Comments (For Professional Developers)

Writing meaningful comments is a skill that can elevate your code quality and make collaboration smoother. Here are some key best practices for writing comments without going overboard.

1. Explain Why, Not What

Your code should already show what it does. Comments should focus on why certain decisions were made, especially if they’re not obvious.

// Using backup API due to high failure rate on the main API
fetchBackupData();

This explains why you’re using a backup API, not just restating the code.

2. Clarify Complex Logic

For complicated algorithms or non-standard solutions, a quick explanation can prevent confusion.

// Binary search for O(log n) efficiency in large datasets
function binarySearch(arr, target) {
  // code here
}

It’s clear why binary search is used without having to understand the entire algorithm immediately.

3. Highlight Known Issues

If your code has limitations or bugs that need attention later, mark them clearly.

// TODO: Improve handling for leap years
function calculateDaysBetween(startDate, endDate) {
  return (endDate - startDate) / (1000 * 60 * 60 * 24);
}

This tells the reader there's an issue to be fixed without digging through the code.

4. Avoid Stating the Obvious

Don’t write comments that repeat what the code says. Only comment where extra context is necessary.

let count = 0; // Initialize count to 0

Here, the comment adds no value because the code is simple and self-explanatory.

5. Explain Unconventional Code

When using an unusual approach, leave a comment to avoid confusion later.

// Intentional type coercion for loose comparison
if (value == '42') {
  // logic here
}

This helps prevent someone from “fixing” your code when the choice was intentional.

6. Keep Comments Updated

Outdated comments can cause more harm than no comments. Always update your comments when the code changes.

// Sorting by age instead of name for performance reasons
function sortUsers(users) {
  return users.sort((a, b) => a.age - b.age);
}

Ensure your comments stay relevant to avoid misleading other developers.

7. Use TODOs and FIXMEs Sparingly

When you know improvements are needed but don’t have time to fix them right away, mark them with TODO or FIXME comments.

// TODO: Optimize this function for better performance
function processArray(arr) {
  // current logic here
}

These flags help others (or future you) know what needs attention.

---

Final Thought

Effective comments make your code easier to understand and maintain. Keep them short, useful, and focused on explaining decisions or complex logic. The goal is to provide value, not clutter the code. By following these best practices, your comments will remain an asset to your project instead of a distraction.

Previous Article:

Console.log Like a Boss: Mastering JavaScript Debugging | The Ultimate Guide to JavaScript Console: Error Logging, Warnings, and More

Next Article:

The Ultimate Guide to Variables in JavaScript: Syntax, Naming, and Reassignment | A Beginner’s Guide to let, const, and var

Ashraf JavaScript Tutorial Programming