How to write meaningful comments in your code

Comments in code are incredibly important because they enable developers to easily understand the code. Without comments, developers would spend more time trying to figure out what the code is doing, increasing the risk of introducing bugs with their changes. Additionally, comments make it easier for developers to collaborate on a project, as they can quickly explain the purpose of a code block to others. Ultimately, meaningful comments help to ensure that code is maintainable and that projects are successful.

Writing useful comments is an essential part of writing quality code. A useful comment should explain why the code is written in a certain way, not just what it does. It should also provide context to the code, such as the business logic or edge cases that the code is handling.

// ⛔️
// Display "message" to user
const notifyUser = (message: string) => {
    alert(message);
}
	
// ✅
/**
 * Success callback function for X request.
 * @param message The message that the user will see
 *
 * @see X request
 */
const notifyUser = (message: string) => {
    alert(message);
}

The correct way of commenting above is called JSDoc and it is a special syntax of documenting your code. Since it is a standard across Javascript applications, there are many different tools that will read through your files, find these comments and generate an actual static documentation website from your codebase.

When writing code comments, make sure to keep it concise and to the point. Avoid lengthy descriptions that don’t add anything to the understanding of the code. It is also important to keep comments up to date. If a code block changes, the comments should reflect the changes. Outdated comments can be very confusing and can lead to mistakes.

Finally, be sure to use meaningful identifiers in your code. Meaningful identifiers make it easier for other developers to understand what a code block is doing. This, in turn, can help to reduce the need for comments in the first place.