Question

我在乔治亚理工学院与一支名为Solar Jackets的团队合作，我们一直在进行“评论危机”。我们有许多成员毕业，并留下无评论的代码。我正在寻求实施评论标准，所以这不会发生，我需要一些建议，以确保我的所有基础都涵盖。

我想要的是以下功能：

一个合并的地方，您可以在其中查看每个功能描述，包括包含，参数，返回类型和一般代码的描述。（根据代码中的注释生成）
在代码本身中，逐行（或接近）描述。

对于我可能遗漏的内容有什么建议吗？是否有任何程序可以自动生成代码编译？我怎样才能让程序员更容易？

Answer 1

你描述的东西让我想起了Doxygen。它有一种格式用于注释代码中的所有实体，包括函数，参数，变量，...... 它可用于通过检查Doxygen生成的警告来强制执行所有操作。它以不同的格式生成源代码的完整文档，如HTML，Latex，PDF，......

许多IDE都知道Doxygen标签，可以与Doxygen集成，以帮助开发人员评论代码。

这是Doxygen评论的一个例子：

/**
 * @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;
}

Answer 2

加强良好的编码习惯。变量名称和方法标题应该是描述性的，并专注于他们正在执行的任务。例如，如果您有一个交换两个元素的方法，则调用它swap()就足够了。
使用文档生成工具，例如Doxygen或Sphinx。
我们鼓励使用其他API（例如Java 7 API）作为可读性的指南，以及做什么（或不做）。

我应该强调太多文档可能会让人分心。让程序员 - 他们的软件正在做什么的专家 - 为文档提供高级概述。如果他们想要或必须让他们按照自己的条件解释复杂或错综复杂的代码。

Answer 3

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

我们使用代码审查会话，以便所有团队成员都能阅读和研究新代码，如果它不干净且易于阅读，则会重构。通常，包括名称表达式的局部变量，不重用变量和为常量文字添加#defines都可以完成这项工作。

Answer 4

关于代码的逐行评论听起来很糟糕。

您需要在函数的开头注释，以确定它的作用。
- 如果参数等不明显，应该讨论它们。
- 否则，它应尽可能简短，最好只有一行。
- 如果功能很复杂，可能需要更大的评论;使用判断。
您通常需要包含公司或项目许可和版权标识的文件标题注释，以及有关文件总体用途的注释。
你应该记录定义的变量（主要应该是static变量;你不使用全局变量，是吗？）。
您可能需要在功能中评论代码段落，最好是短（一行）注释。
偶尔，您需要记录非显而易见或模糊不清（可能参考相关的错误报告）。
除局部变量定义外，你应该很少需要尾注释。

否则，代码应该在很大程度上解释自己，使评论变得多余。

请注意，不描述当前代码的注释会令人讨厌。仅在昨天，我删除了1990年明确添加的评论 - 日期在评论中 - 描述了1990年的现状，当时一个特定的函数模拟了“可变参数”。代码早已更新，因此该函数被视为具有7个固定参数;不需要时，最后四个可以为null。因此，评论不再准确，而是十年或更长时间。它去。为什么没有人注意到它？可能是因为没有其他人第一次阅读该文件而没有导师指导他们通过错误的评论。或者也许是因为评论距离函数太远了（评论和它错误描述的函数之间有一个完全独立的，虽然很小的函数）。因此，30行（不准确）评论终于进入了天空中的位。

另请注意，专家需要的内容以及新手对同一段代码所需要的内容可能完全不同。你必须在什么级别的评论有意义上做出判断，但我建议在论文中犯错误，因为当需要修改代码时，两个描述中的一个将无法正确维护，并且可能性是没有维持的评论。对于初学者而言，误导性评论比专家更为可怕！因此，请确保您没有任何可避免的评论，因此无法获得不准确的评论。

评论标准C.

4 个答案: