Benefits of commenting in programming

Benefits of commenting in programming and best practices for writing effective comments

Why comments are important in programming

How to write effective comments

To write effective comments, there are a few tips and best practices to keep in mind.

• Keep comments concise and to the point. Avoid rambling or including unnecessary information.
• Use clear and straightforward language. Avoid jargon or technical terms that may not be familiar to all readers.
• Use comments to explain the why, not just the what. Comments should provide context and explain the reasoning behind the code, not just describe what the code does.
• Comment at the appropriate level of abstraction. Avoid commenting on every single line of code, but also avoid commenting only on high-level concepts without providing any specific details.
• Keep comments up to date. Make sure to update the comments if the code changes to reflect the new functionality.

There are also common mistakes to avoid when commenting:

• Don’t use comments as a crutch. Instead of using comments to explain poor code, use them to clarify and enhance well-written code.
• Don’t repeat the code in the comments. Comments should provide additional information, not repeat what’s already in the code.
• Don’t use comments to state the obvious. If the code is self-explanatory, there’s no need for a comment.

Comment types

Different types of comments can be used in different situations:

• Single-line comments, which start with “//” or “#”, are used for short explanations or notes.
• Multi-line comments, which start with “/” and end with “/”, are used for longer explanations or notes.
• Document comments, often called Jsdoc or Doxygen comments, generate documentation automatically. They usually start with a /*_ and end with a _/.
• Inline comments, which are placed on the same line as the code they’re commenting on, are used to provide more specific information about a particular line of code.

In summary, writing effective comments is an essential part of good coding practice. It makes the code more understandable and maintainable. Keep comments concise, clear, and to the point; avoid common mistakes; and use different types of comments depending on the situation.

Conclusion

• The book “Clean Code: A Handbook of Agile Software Craftsmanship” by Robert C. Martin, covers commenting and other best practices for writing clean and maintainable code.
• The website “comments.app” provides a curated list of articles, videos, and podcasts on the topic of commenting.
• The website “stackify.com” has many articles that cover best practices for commenting and other aspects of software development.

Commenting is an important part of programming because it makes the code easier to read, easier to fix, and better overall. It is important to make commenting a habit, and for those who want to learn more about commenting and best practices, there are many resources available.

Comments in programming example

Examples of good and bad commenting practices can help you understand how to write effective comments.

Here is an example of good commenting practice:

In this example, the comment at the top of the function provides a clear explanation of what the function does, including the input (n) and the output (returns). It also uses the appropriate type of comment (multi-line comment) for a longer explanation.

Here is an example of bad commenting practice:

In summary, good commenting practice should be clear and concise and provide context and explanations for the code. The comments should not repeat what’s already in the code and should not be used to explain bad code. The appropriate type of comment should be used, and over-commenting should be avoided.