Comments in the code are like a museum guide: they tell you what you're looking at, provide context, and enrich your understanding of the work. In JavaScript, as in other programming languages, commenting your code is a practice that can transform an indecipherable script into a comprehensible narrative, facilitating both maintenance and collaboration.
Why Comment?
When writing code, you are telling a story. Comments act as marginal notes, offering explanations and justifications. Often the why behind a block of code is more valuable than the how, especially when you review your own code after some time or when a new developer joins the project.
Commenting is also a sign of professionalism. Well-commented code is easier to debug, update and reuse. Of course, as with everything, moderation and common sense are key – too many comments can be as harmful as too little.
Good Practices for Commenting Code
The quality of the comments often dictates the usefulness of the comments. Here are some guidelines to improve the readability and effectiveness of your JavaScript comments.
Comment on 'Why' more than the 'What'
The code should be clear enough to explain what it does. Use comments to explain why a certain decision was made or why a piece of code is necessary. This approach helps prevent redundancy and focuses attention on the intent of the code.
Use Comments to Clarify Complex Code
Sometimes certain operations or algorithms are inherently complex and cannot be simplified further. In these cases, comments are essential to provide insight into the internal workings and logic of the code.
Keep Comments Updated
An outdated comment is worse than no comment. Be sure to review and update comments when changing code to avoid confusion.
Use Documentation Tools
Tools like JSDoc can be extremely useful for generating documentation of your code. These tools allow you to write comments in the code that can then be automatically transformed into accessible, well-formatted documentation.
Avoid Unnecessary Comments
Avoid commenting on code that is self-explanatory. It is also preferable to avoid block closing comments unless the block is excessively long and it really improves readability.
Comment During Code Writing
Don't leave the comments for the end. Comment as you write; It will be easier for you to remember your reasoning and decisions.
Formatting Standards
Decide on a comment format standard and keep it consistent throughout the project. This includes capitalization, punctuation, and comment structure.
Using TODO and FIXME
Use specific tags like ALL to mark pending tasks and FIXME to indicate problems that need to be corrected. This makes it easier to quickly identify areas of the code that require additional attention.
Regarding multi-line comments, it is common to use /*...*/ for extensive descriptions or documentation of functions and // for short single-line comments or to quickly comment out a block of code while debugging.
Examples of Good Practices in Comments
A good comment makes the difference between a frustrated coworker and one who thanks you for your foresight. Let's look at some examples:
// Bad practice: Redundant comment // Declare the variable sum and initialize it to 0 let sum = 0; // Good practice: Explanation of 'why' // Initialized to 1 due to the requirement to include the initial number in the calculation let product = 1; // Bad practice: Deprecated comment let total = 0; // Adds the total of the items in the list (not only does it add, it also does more operations)Additional Tools and Resources
To take your code commenting skills to the next level, don't hesitate to explore code documentation tools and online resources. On the website of NelkoDev You'll find more tips and best practices that may be of interest to you.
In short, writing useful comments is an art that balances the amount of detail with clarity and conciseness. Outstanding comments will serve as navigational charts in the sea of software complexity – they illuminate the purpose and enhance the understandability of your code. Remember, the next time a coworker can understand your months-old code with nothing more than a quick glance at your comments, you'll know that you've created more than just lines of code: you've built a source of knowledge.
And if you ever need help or have questions about improving your code, feel free to contact me via NelkoDev contact. I'm here to help you with your coding challenges!
English 
Spanish