Effective Comments and Documentation in TypeScript

Hello and welcome to this lesson on comments and documentation. In our previous lessons, we concentrated on the value of using meaningful names and crafting well-organized functions to enhance the readability and maintainability of clean code. In this session, we'll shift our focus to mastering the art of writing effective comments and documentation, which act as guiding lights through complex sections of the code.

Comments are a vital instrument for clarity, but they must be wielded judiciously. Below are scenarios where comments are truly beneficial:

• Legal Comments: ✅ Use these to specify legal obligations and protect intellectual property.
• Clarification: ✅ Aid understanding by explicating complex or non-obvious code logic.
• Warning of Consequences: ✅ Highlight potentially risky operations to prevent unintended effects.
• TODO Comments: ✅ Track tasks or improvements that need to be addressed in the future.
• TSDoc for Public APIs: ✅ Provide essential documentation for API usability and developer guidance.

Here are situations where comments can be detrimental:

• Redundant Comments: 🔴 Eliminate comments that merely reiterate code.
• Noise Comments: 🔴 Avoid comments that offer no meaningful insight.
• Commented-Out Code: 🔴 Remove old code unless retaining it is justified with a reason.
• Unnecessary TSDoc: 🔴 Avoid TSDoc for methods that don't require explanation, such as trivial ones.

Legal comments are key to ensuring proper acknowledgment and protection of intellectual property. They're used to specify licensing or copyright information, offering legal clarity to users and contributors about the code's usage terms. This practice not only fosters trust but also shields against potential legal disputes:

/*
 * Copyright 2023, XYZ Corporation.
 * Licensed under the Apache License, Version 2.0.
 */

These comments ensure that users and contributors are aware of the legal rights and restrictions associated with the code.

Use comments to unravel complex logic in the code. It's not about stating the obvious but about offering insights where the code might be difficult to follow. This guidance can be invaluable for future developers or even your future self if you return to the code months or years later:

// 🚀 Calculating square root using Newton's method for better precision
let sqrtValue = computeSquareRoot(value);

This comment clarifies the method's use and is helpful for future reference or updates.