How to Write Clear and Effective Code Comments in JavaScript with Better Comments

When working in JavaScript, writing clear and structured comments is essential for maintainable code. The Better Comments extension for Visual Studio Code takes this further by color-coding different types of comments to increase readability. You can download it here. Let’s explore how to use it for best commenting practices.

Types of Comments with Better Comments

Better Comments categorizes comments by purpose, including the following types:

1. TODOs (// TODO:): Mark tasks or improvements.
2. Important Notes (// !): Highlight key areas in your code.
3. Questions (// ?): Use for clarifying logic or seeking feedback.
4. Explanations (//): Standard comments to explain complex code.

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

Instead of restating what the code does, focus on why specific code is necessary. Better Comments allows us to use // ? to mark questions or explanations that clarify reasoning.

Example:

javascript
Copy code
// ? Increment by 2 to loop through only odd numbers
for (let i = 1; i < 10; i += 2) {
  console.log(i);
}

2. Use Descriptive Comments for Complex Logic

For complex logic, the //! notation can indicate important sections in Better Comments. This helps future maintainers quickly recognize essential explanations.

Example:

javascript
Copy code
//! Custom sort function to prioritize items with the highest scores, then alphabetically by name
items.sort((a, b) => {
  if (a.score === b.score) return a.name.localeCompare(b.name);
  return b.score - a.score;
});

3. Comment Functions and Classes

Provide purpose, inputs, and outputs at the beginning of functions and classes. Use Better Comments for clarity: // ? for explanatory comments and // TODO for pending improvements.

Example:

javascript
Copy code
// ? Calculates the total price of items in the cart
// TODO: Add handling for discount codes in future iterations
/**
 * Calculates the total price of items in the cart.
 * @param {Array} items - Array of item objects with price and quantity.
 * @returns {number} - The total price.
 */
function calculateTotal(items) {
  return items.reduce((total, item) => total + item.price * item.quantity, 0);
}

4. Avoid Redundant Comments

Avoid stating obvious information in comments. If the function name generateID() is clear, you can skip the comment entirely, or use a simple // ? comment to note specific design choices.

Example (to avoid):

javascript
Copy code
// ? Generates a unique identifier string
function generateID() {
  return Math.random().toString(36).substr(2, 9);
}

5. Use Consistent Style and Structure

Following a consistent commenting style, especially with Better Comments colors, helps team members understand comments quickly and spot important notes.

6. Keep Comments Up-to-Date

Outdated comments mislead readers. With Better Comments, you can use // TODO for reminders or //! to highlight changes.

7. Document Known Issues or Workarounds

If the code has workarounds or known limitations, document them with Better Comments. The // ! style can be used for critical issues, drawing attention to any known bugs or necessary fixes.

Example:

javascript
Copy code
//! Known issue: This method does not support nested objects; update expected in v2.0
function shallowClone(obj) {
  return { ...obj };
}

8. Comment Edge Cases

Use // ? in Better Comments to highlight edge cases, helping future readers understand why certain handling exists.

Example:

javascript
Copy code
// ? Handle null values as valid input to indicate 'unknown' data in our system
function processData(input) {
  if (input === null) return 'unknown';
  return input;
}

Conclusion

With the Better Comments extension, you can make your JavaScript comments more effective by using color-coded tags to clarify intentions, mark tasks, highlight important sections, and handle edge cases. This approach ensures your code is easy to understand, maintain, and extend.

Happy coding and commenting with Better Comments!