3

我与佐治亚理工学院的一个名为 Solar Jackets 的团队合作，我们一直处于“评论危机”之中。我们有很多成员毕业了，留下了无注释的代码。我正在寻求实施一个评论标准，这样就不会发生这种情况，我需要一些建议来确保我已经涵盖了所有的基础。

我想要的是以下功能：

  • 一个统一的地方，您可以在其中查看每个函数的描述，包括包含、参数、返回类型和代码的一般描述。（从代码中的注释生成）

  • 在代码本身中，逐行（或接近）描述。

对我可能遗漏的内容有什么建议吗？有没有可以自动生成代码编译的程序？我怎样才能让程序员更容易做到这一点？

4

4 回答 4

9

你的描述让我想起了 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;
}
于 2012-04-18T01:26:45.310 回答
2

  • 养成良好的编码习惯。变量名称和方法标题应该是描述性的，并特别关注他们正在执行的任务。例如，如果您有一个交换两个元素的方法，调用它就swap()足够了。

  • 使用文档生成工具，例如Doxygen或Sphinx。

  • 鼓励使用其他 API（例如Java 7 API）作为可读性指南，以及该做什么（或不做什么）。

我可能应该强调，过多的文档会非常分散注意力。让程序员——他们是他们的软件在做什么方面的专家——给出一个高层次的概述，以便于记录。如果他们想要或必须这样做，那么让他们按照自己的方式解释复杂或令人费解的代码。

于 2012-04-18T01:30:07.013 回答
1

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

我们使用代码审查会议，以便所有团队成员都可以阅读和研究新代码，如果它不干净且不易于阅读，则会对其进行重构。通常，在命名表达式中包含局部变量，而不是重用变量并为常量文字添加#defines 就可以完成这项工作。

于 2012-04-18T01:32:38.370 回答
1

对代码的逐行注释听起来很可怕。

  • 您需要在函数的开头添加注释来确定它的作用。
    • 如果参数等不明显，则应进行讨论。
    • 否则，它应该尽可能简短，最好只有一行。
    • 如果函数比较复杂，注释大一点可能比较合适；使用判断。
  • 您通常需要包含公司或项目的许可证和版权标识的文件标题注释，以及有关文件总体用途的注释。
  • 您应该记录定义的变量（应该主要是static变量；您不使用全局变量，对吗？）。
  • 您可能需要对函数内的代码段进行注释，最好使用简短（一行）注释。
  • 有时，您需要记录不明显或晦涩难懂的内容（可能参考相关的错误报告）。
  • 除了局部变量定义之外，您应该很少需要尾部注释。

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

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

还要注意，对于同一段代码，专家需要什么和新手需要什么可能完全不同。您必须判断什么级别的评论才有意义，但我建议您在文章中犯错，因为当需要修改代码时，两个描述中的一个将无法正确维护，并且很可能是未维护的评论。对于新手来说，误导性的评论比专家更可怕！因此，请确保您不会因为没有任何可避免的评论而获得不准确的评论。

于 2012-04-18T01:50:30.073 回答