我与佐治亚理工学院的一个名为 Solar Jackets 的团队合作，我们一直处于“评论危机”之中。我们有很多成员毕业了，留下了无注释的代码。我正在寻求实施一个评论标准，这样就不会发生这种情况，我需要一些建议来确保我已经涵盖了所有的基础。
我想要的是以下功能：
一个统一的地方，您可以在其中查看每个功能说明， 包括包含、参数、返回类型和一般 代码的描述。 （从代码中的cmets生成）
在代码本身中，逐行（或接近）描述。
对我可能遗漏的内容有什么建议吗？有没有可以自动生成代码编译的程序？我怎样才能让程序员更容易做到这一点？
【问题讨论】：
养成良好的编码习惯。变量名称和方法标题应该是描述性的，并特别关注他们正在执行的任务。例如，如果你有一个交换两个元素的方法，调用它swap() 就足够了。
鼓励使用其他 API（例如 Java 7 API）作为可读性指南，以及该做什么（或不做什么）。
我可能应该强调太多文档可能会非常分散注意力。让程序员——他们是他们的软件在做什么方面的专家——给出一个高层次的概述，以便于记录。如果他们愿意或必须这样做，那么让他们按照自己的方式解释复杂或令人费解的代码。
【讨论】：
对代码的逐行注释听起来很可怕。
static 变量；您不使用全局变量，对吗？）。否则，代码应该在很大程度上解释自己，从而使 cmets 变得多余。
请注意，不描述当前代码的 cmets 是令人讨厌的。就在昨天，我删除了一条在 1990 年明确添加的评论——日期在评论中——描述了 1990 年的现状，当时一个特定的函数正在模拟“变量参数”。代码早已更新，因此函数被视为具有 7 个固定参数；最后四个在不需要时可以为空。因此，评论不再准确，而是十年或更长时间。它去。为什么其他人没有注意到？可能是因为没有人第一次阅读该文件时没有导师指导他们越过错误的评论。或者可能是因为注释离函数太远了（在注释和它错误描述的函数之间有一个完全独立的，尽管很小的函数）。所以，30 行（不准确的）评论终于落到了空中。
还要注意，对于同一段代码，专家需要什么和新手需要什么可能完全不同。您必须判断什么级别的评论才有意义，但我建议您在文章中犯错，因为当需要修改代码时，两个描述中的一个将无法正确维护，并且很可能是没有维护的 cmets。而且误导性的 cmets 对新手来说比对专家来说更可怕！因此，请确保您不会因为没有任何可避免的 cmets 而获得不准确的 cmets。
【讨论】：
在我的新工作中，我们尽量避免使用 cmets。代码应该是自记录的。在棘手的代码或错误修复等方面允许使用一些小的 cmets，但日常编程根本不包括 cmets。
我们使用代码审查会议，以便所有团队成员都可以阅读和研究新代码，如果代码不干净且不易于阅读，则会对其进行重构。通常，在命名表达式中包含局部变量，而不是重用变量并为常量文字添加#defines 就可以了。
【讨论】：
你的描述让我想起了 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;
}
【讨论】：