评论标准C

我在佐治亚理工大学与一个名为“太阳能夹克”的团队合作，我们一直在经历一场“评论危机”。我们有许多成员毕业了，留下了无注释的代码。我希望实现一个评论标准，这样就不会发生这种情况，我需要一些建议，以确保我涵盖了我的所有基础

我想要的是以下功能：

• 一个整合的地方，您可以在这里查看每个功能描述， 包括include、参数、返回类型和常规 代码说明。（根据代码中的注释生成）

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

---

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

你所描述的让我想起了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;
}

• 强化良好的编码习惯。变量名和方法头应该是描述性的，并且特别关注它们正在执行的任务。例如，如果您有一个交换两个元素的方法，那么调用它

  swap（）

  就足够了

• 使用文档生成工具，如或

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

---

我可能应该强调，太多的文档可能会让人分心。让程序员（他们是软件开发方面的专家）为文档提供一个高层次的概述。如果他们想或必须这样做，那么就让他们用自己的术语解释复杂或复杂的代码。

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

---

我们使用代码审查会议，这样所有团队成员都可以阅读和研究新代码，如果代码不干净、不容易阅读，就进行重构。通常，包括局部变量来命名表达式，不重用变量和为常量文本添加#defines来完成这项工作。

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

• 您需要在函数的开头添加注释，以确定函数的功能。
  • 如果参数等不明显，则应进行讨论
  • 否则，它应该尽可能简短，最好只有一行
  • 如果函数很复杂，可能需要更大的注释；运用判断
• 您通常需要一个文件头注释，其中包含公司或项目的许可证和版权标识，以及关于文件总体用途的注释
• 您应该记录定义的变量（应该主要是

  静态

  变量；您不使用全局变量，是吗？）
• 您可能需要对函数中的代码段进行注释，最好使用短（一行）注释
• 有时，您需要记录不明显或模糊的错误（可能需要参考相关的错误报告）
• 除了局部变量定义之外，您应该很少需要尾部注释

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

请注意，不描述当前代码的注释是一个麻烦。就在昨天，我删除了一条在1990年明确添加的注释——日期在注释中——描述了1990年的现状，当时一个特定函数正在模拟“可变参数”。代码已经更新很久了，因此函数被视为有7个固定参数；不需要时，最后四个可以为空。因此，这一评论不再准确，而是十年或更长的时间。它去了。为什么其他人没有注意到？可能是因为没有人在没有导师的指导下第一次阅读该文件，从而避免了错误的评论。或者可能是因为注释与函数的距离太远（注释和它错误描述的函数之间有一个单独的函数，尽管很小）。因此，30行（不准确的）评论最终进入了天空

---

同样要注意的是，对于同一段代码，专家和新手所需要的可能是完全不同的。你必须对评论的级别做出判断，但我建议你在文章中犯下斯巴达式的错误，因为当需要修改代码时，两种描述中的一种不会得到正确维护，很可能是评论没有得到维护。对于新手来说，误导性评论比专家更可怕！因此，请确保您不会因为没有任何可避免的评论而得到不准确的评论。

？这有点晚了，但我想说的是，我的公司大约在一年前实施了一项编码标准，取得了很好的效果。最重要的一点是评论为什么，而不是什么。通过阅读代码，“什么”是显而易见的，但“为什么”是更难确定的。我们在很大程度上也是这样做的，但对于我们的许多项目来说，进展是停滞不前的。我们有高级设计团队，我们无法控制，创建代码，然后在学期末消失。