What are the best coding standards for effective code commenting?

由人工智能和领英社区提供技术支持

Code comments are an essential part of system development, as they help explain the logic, purpose, and functionality of your code to yourself and others. However, not all comments are created equal, and some can be more harmful than helpful. In this article, we will explore the best coding standards for effective code commenting, and how to avoid common pitfalls and bad practices.

本文章的要点总结

Comment the "Why":

Explain the reasoning behind your code to aid future understanding. This includes documenting your assumptions, design choices, and any peculiarities that deviate from the norm.
Update with code:

When you modify your code, ensure you also adjust the comments. Stale commentary can mislead and confuse, so keeping them in sync is crucial for clarity.

本摘要由 AI 和以下专家提供支持

Pradeep Dash

IT & Business Consulting | Energy &…
Vishnu Santhosh

Embedded Software Engineer @ Qualcomm |…

1 Why comment your code?

Code comments are not just for documentation or debugging. They are also a way of communicating your intentions, assumptions, and design choices to other developers, reviewers, or maintainers of your code. By commenting your code, you can make it easier to read, understand, and modify, as well as prevent errors, bugs, and confusion. Code comments can also help you adhere to coding standards, follow best practices, and improve the quality and consistency of your code.

添加您的观点

Pradeep Dash

IT & Business Consulting | Energy & Utilities
举报内容
It's very important to write readable code. It makes the intention of code snippets more understandable and supportable in future. I always emphasize with my developers to properly comment and follow indenting appropriately while coding, in a way the support document goes with your code - keep it to the point and concise enough so that someone other than the developer can understand while debugging.

已翻译

赞
Siddhartha Sood

True Blue IBM'er | Executive Architect for Hybrid Cloud | Travel & Transportation Architecture Lead | IBM Master Inventor | IBM Academy of Technology Member | Mentor
举报内容
“Why” is the most important aspect behind code documentation. Often when developers are asked to document code, it is not really clarified as to why it is needed. Hence many developers tend to focus more on documenting the functionality rather than documenting why something was done the way it was done. Example the intent behind a class or a method. Principles of clean code also stress that the code itself should be self explanatory

已翻译

赞

2 What to comment and what not to comment?

One of the most important principles of code commenting is to comment the why, not the what. This means that you should focus on explaining the rationale, logic, or reasoning behind your code, rather than describing what it does. The code itself should be clear and self-explanatory, using meaningful names, proper indentation, and consistent formatting. If you need to comment on what your code does, it may be a sign that your code is too complex, obscure, or redundant, and that you should refactor it to make it simpler and cleaner.

Another principle is to comment the exceptions, not the rules. This means that you should only comment on the parts of your code that are unusual, tricky, or non-obvious, and that deviate from the normal or expected behavior. For example, you should comment on why you used a specific algorithm, library, or data structure, or why you handled a certain edge case or error condition. You should not comment on the parts of your code that are straightforward, standard, or obvious, as they would only clutter your code and add noise.

添加您的观点

Siddhartha Sood

True Blue IBM'er | Executive Architect for Hybrid Cloud | Travel & Transportation Architecture Lead | IBM Master Inventor | IBM Academy of Technology Member | Mentor
举报内容
Well articulated already. The intent is not to comment on what the code does but more on why it works in a certain way. Many times as a developer who is working on the code, the focus is to finish the feature fast and move into the next one but spending those few minutes on documentation go a long way in increasing the overall maintainability of the code.

已翻译

赞

3 How to write good comments?

Writing good comments is essential for communicating the purpose and functionality of your code. To do so, you should use a comment style compatible with your programming language and IDE, such as single-line, multi-line, or docstring comments. Additionally, use a comment convention that is consistent with your project or organization, such as the Javadoc, Doxygen, or PEP 8 standards. Also, be respectful and professional in your tone and keep the comments at an appropriate level for your audience and purpose. Finally, use a balanced frequency of comments to avoid over-commenting or under-commenting your code.

添加您的观点

Siddhartha Sood

True Blue IBM'er | Executive Architect for Hybrid Cloud | Travel & Transportation Architecture Lead | IBM Master Inventor | IBM Academy of Technology Member | Mentor
举报内容
This aspect may be overlooked and hence is is a great idea to have your peers look at your code and associated comments to provide feedback. This can be both formal reviews or if through informal reviews. Practices such as pair programming should also focus on code comments and overall documentation.

已翻译

赞

4 How to maintain and update your comments?

Comments should be dynamic and evolve along with the code, as outdated, misleading, or incorrect comments can cause more harm than good. To maintain and update your comments, you should review and revise them regularly to ensure they match your code and logic. Additionally, remove or edit any comments that are no longer relevant, accurate, or useful. Furthermore, use a version control system such as Git or SVN to track and manage your code and comment changes, and use meaningful commit messages and comments. Finally, consider using a code review tool like GitHub or CodeGuru to check and improve your code and comment quality, as well as get feedback from other developers.

添加您的观点

5 How to use code commenting tools and resources?

Code commenting is not only a manual task, but also an automated one. You can use various tools and resources to help you write, generate, or enhance your code comments, making them more effective and efficient. For example, code editors and IDEs such as VS Code or PyCharm provide syntax highlighting, auto-completion, and linting for your code and comments, allowing you to follow coding standards and best practices. Code documentation generators like Sphinx or JSDoc extract and compile your code comments into HTML, PDF, or other formats. Additionally, code comment analyzers like CodeComment or Commentz evaluate and score your code comments based on readability, completeness, and consistency. Lastly, code comment libraries and templates like Google Style Guides or Awesome Comments provide examples and guidelines for writing code comments in different languages, domains, and scenarios.

添加您的观点

6 Here’s what else to consider

This is a space to share examples, stories, or insights that don’t fit into any of the previous sections. What else would you like to add?

添加您的观点

Vishnu Santhosh

Embedded Software Engineer @ Qualcomm | Linux | Kernel & Device Drivers | C & C++ | Open Source Developments
举报内容
1. Focus on the "Why" and not on the "What". If you need to explain what the code is doing, simplify the code instead of making the comment complex. 2. Trust your co-workers skills. You don't need to restate what the code is doing line by line. Keep the comments high-level. 3. Document the things someone need to know like assumptions, dependencies etc. 4. Follow the standards of the code you are editing. 5. When you update the code, update the relevant comments as well. No one will ever come and edit the comment for your code changes.

已翻译

赞

System Development

+ 关注

给文章评分

我们借助人工智能创建了此文章。您认为这篇文章怎么样？

很棒不太好

举报此文章

查看全部

What are the best coding standards for effective code commenting?

1

2

3

4

5

6

1 Why comment your code?

2 What to comment and what not to comment?

3 How to write good comments?

4 How to maintain and update your comments?

5 How to use code commenting tools and resources?

6 Here’s what else to consider

System Development

给文章评分

感谢您的反馈

更多System Development相关文章

更多相关阅读内容

What are the best coding standards for effective code commenting?

1

2

3

4

5

6

1 Why comment your code?

2 What to comment and what not to comment?

3 How to write good comments?

4 How to maintain and update your comments?

5 How to use code commenting tools and resources?

6 Here’s what else to consider

System Development

给文章评分

感谢您的反馈

查看其他技能