代码文档：公共与非公共？

我就是那些思维定式的人，他们所写的代码应该是不言自明的，并且应该像书一样阅读。

但是，在开发供他人使用的库代码时，我尝试将尽可能多的文档放在头文件中；这就提出了一个问题：非公开的记录方法是否值得？他们不会直接使用它们，实际上，它们不能。同时，如果我分发原始代码（尽管很不情愿），那些非公共方法将是可见的，可能需要解释。

只是寻找您在旅途中看到或使用的一些标准和做法。

我绝不会考虑因为“最终用户”不会使用它们而忽略内部文件。代码维护是包含所有组件的文档注释的充分理由，事实上，尤其是对于内部组件来说，注释通常是最复杂（且经常更改）的部分。

话虽如此，为了保持抽象，可能存在使它们限于非标头源代码（而不是公开记录）的有效理由。

请注意，这都是相当主观的。

好的，我也将评论/记录的方式添加到图片中以供选择。理由是我避免描述仅在标头中声明的函数或成员函数。一方面，我担心会给标题增加过多的噪音。另一方面，文档和定义一起使维护人员更容易匹配。Doxygen不在乎这两种方式，并且可以根据需要过滤掉私人用户。

在课程标题中：

• 包含标题（为什么）
• 始终定义类（目的和职责）
• 纯虚拟功能始终（完全合同）
• 内联函数，除非自我解释的吸气剂
• 其他声明的类型，除非不言自明
• 静态数据成员（为什么）
• 其他数据成员，除非不言自明
• 宏（如有）（合同以及原因）

在类的实现代码中：

• 本地声明与标头中的相同
• 始终具有功能定义（完整合同）
• 成员函数定义始终（完整协定或虚拟覆盖根的引用）
• 定义的静态变量（目的）

在模板标题中：

• 以上合并
• 模板参数的合适/不合适类型
• 静态检测适应性的程度

将private:在私人部分的开头是用户可能需要的所有文件。

文档是值得的一天，它有助于以简短的方式解释用例和故事。有多少代码是可以自我解释的，它无法像讲故事的几行那样轻松地解释业务。该代码肯定会要求用户遵循逻辑以了解发生了什么。:-)我的2美分...

绝对！

该代码应具有自我记录性，这是一个口号。但是，我要说的是，私有代码比公共代码需要更多甚至更多的文档，因为通常在这里，大多数假设通常都会发生，只是因为编码人员认为它会一直处于黑暗中。因此，几个月后，当您遇到错误时，您将花时间尝试记住代码背后的想法（也许是您自己）。

文档不应该作为礼物送给他人。文档，从各个方面来说（精心挑选的变量名，自记录类名，组织良好的代码，正确地分割的方法等）都是可能与您接触到代码（包括您自己）的每个人的礼物。