问评论标准C

EN

你的描述让我想起了氧气。它具有注释代码中所有实体的格式，包括函数、参数、变量、.它可以用来强制所有的东西都是通过检查DO2生成的警告来记录的。它以不同格式生成完整的文档，如HTML、Latex、PDF、.

许多IDE都知道know标签，可以与DO2集成，以帮助开发人员对代码进行注释。

下面是DO2评论的一个例子：

/**
 * @brief This function does blah blah.
 * @param test blah blah parameter.
 * @return 0 if blah blah passed.
 */
uint32_t TestFunction( uint32_t test )
{
    return 0;
}

• 养成良好的编码习惯。变量名称和方法头应该是描述性的，并且应该特别关注它们正在执行的任务。例如，如果您有一个交换两个元素的方法，那么调用它swap()就足够了。
• 使用文档生成工具，如含氧或狮身人面像。
• 鼓励您使用其他API(如Java7API )作为可读性指南，以及应该做什么(或不做)。

我应该强调的是，太多的文档可能会让人分心。让程序员--他们是软件所做工作的专家--为文档提供一个高层次的概述。如果他们想，或者必须，让他们用他们自己的术语解释复杂或复杂的代码。

在我的新工作中，我们尽量避免使用评论。代码应该是自我记录的。一些小的注释是允许在棘手的代码，或错误修复等，但日常编程中根本不包括注释。

我们使用代码评审会话，这样所有的团队成员都可以阅读和学习新代码，如果代码不干净、不容易阅读，则需要重构。通常，包括局部变量来命名表达式，而不是重用变量和为常量文字添加#defines来完成这项工作。