源代码中的注释 [英] Comments in source code

问题描述

如何保持源代码有良好的文档/注释？是否有一个工具可以在Unix平台上为C ++生成评论的框架？

How to keep the source code well documented/commented? Is there a tool to generate a skeleton for comments on the Unix platform for C++?

一般来说，对于大约100行的文件，建议多少行注释代码？

In general, how many lines of comments is recommended for a file with around 100 lines of code?

推荐答案

通常，最好让代码本身解释它评论有描述为什么这样。没有数字可以坚持。如果你的100行代表自己，不要评论或只是在开始时提供摘要。

Generally, it's best to let the code itself explain what it does, whereas the comments are there to describe why it's like that. There is no number to stick to. If your 100 lines speak for themself, don't comment at all or just provide a summary at the beginning. If there is some knowledge involved that's beyond what the code does, explain it in a comment.

如果你的代码太复杂，无法解释自己，那么这可能是一个重构的原因。

If you're code is too complicated to explain itself, then that may be a reason to refactor.

这样，当您更改实现时，您不需要更改注释，因为您的注释不重复代码。由于设计的原因很少改变，因此为了清楚起见，在评论中记录它们是安全的。

This way, when you change the implementation you don't need to change the comments as well, as your comments do not duplicate the code. Since the reasons for the design seldomly change it's safe to document them in comments for clarity.

这篇关于源代码中的注释的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！