C++ 准备发布的公共标题

我很想听听你有什么例行程序来清理你的公共头文件 分发给客户

我想听听你对以下几点的看法：

不用于外部消费的注释。一般来说，我喜欢把文档放在身边 对于这样的代码和注释，共享可能不是一个好主意：

/**
 * @todo Should we change the signature of this function to
 * make it obvious that xxx is really yyy?
 */

或许：

/**
 * @todo Add support for feature X
 */

不一致的选项卡样式：

void functionA(int a, 
     int b,
     int c,
     int d);

void functionB(int a,
               int b,
               int c);

---

有没有什么工具可以为发布准备标题或代码？

在任何涉及多个开发人员的项目中，在任何延长的时间段内以及随后发布的源代码中，您都应该扫描淫秽内容（以及其他您不应该说的话，例如，“我的老板让我这么做”，“这段代码很糟糕”等）。此外，拼写检查注释也会有所帮助，由于人们拼写错误，会影响您的可信度。

请确保您的标题不会生成任何编译器警告。

如果您有文档编码标准/格式，通常会更好，客户会看到开发人员在首次创建代码时会遵循这些标准/格式，所以，您不会像现在这样在发布之前花时间清理代码

---

另外，VisualStudio和其他几个IDE都有一个“自动格式化”选项，您可以在其中设置样式，并将其应用于代码（选项卡、空格等）。我想这正是你在这里想要的。

我对这个主题不太熟悉，但对于开源项目，你通常会在标题的顶部有许可证和版权声明。这可以避免几个司法问题。

G'day

在C++中，我喜欢用公共接口尽可能多地解耦实现。 您还应确保所有样板文件（如版权声明）一致且最新，例如今天发布的代码的版权不会在2008年到期

在命名约定、格式、布局和类设计方面，在所有公共头文件中保持一致，否则会给客户留下不专业的印象

确保头文件中没有“使用”声明。误用“使用”dec会导致严重的副作用

如前所述，确保标题不会生成任何警告

最后。确保你有一些好的API文档和你的头文件

不要像一家提供知名邮政编码查找产品的公司。C API的第一个版本附带了大量基于Windows GUI版本的最少文档。头文件只是由其参数只有类型而没有名称的函数组成。而且没有任何评论

解决函数实际作用的唯一方法是对提供的简单查找示例程序进行反向工程，并对其进行反向工程

---

尽管如此，在设法做到这一点后，我每年为BBC的贫困儿童节省了数万英镑，因为为筹款包提供的地址比往年更可能是正确的

根据我的经验，定期自动清理内部使用的标题以供公众使用是一项艰巨的任务，而且肯定容易出错。最终，不一致的格式或不恰当的评论将不可避免地蔓延开来

---

在许多情况下，您最好将所有内容包装到一个小而干净的界面中，该界面的标题总是尽可能保持干净和注释；例如，对该文件的修改应该经过一个特别仔细的审查过程。

删除粗糙的评论同样重要的是添加必要的评论。您可能需要添加的内容：

• 版权/使用条款标题
• 支持的联系信息
• 文档链接（如果在线提供）
• 公共接口的文档（返回值、参数、前置和后置条件等）
• 已公开但不用于生产的功能/方法的警告

始终让某人（最好不止一人）检查标题，以查找任何看起来不专业的内容。您可以先使用代码格式化程序和其他自动工具

对于评论，让他们寻找任何不专业或试探性的东西。纠正拼写错误。确保它们是准确的。有一个标准的格式，并坚持它

检查所有标识符名称。它们应该符合风格指南，并有专业的名称

确保所有必要的评论都在那里。这包括顶部的版权和联系信息。提出一种记录类等的标准方法，并加以实施

---

基本上，从我的观点来看，你希望你的标题看起来像是由没有创造力或幽默感的无人机制作的，但他们是完全一致的（有点像CPA刻板印象）。（这有点像要求你的开发人员在客户访问办公室时穿西装——如果客户看不到你的开发人员的真实面目，他们会更高兴。）

+1用于纠正拼写和淫秽内容。我确信我不允许（潜意识地）假设不会拼写的人不能被信任来编写可靠的代码。如果你不擅长拼写，找其他人检查一下。检查所有评论，确保它们看起来专业。不要依赖任何类型的自动扫描。你不希望你的客户读到像“我的老板让我这样做”或“我希望这行得通”这样的东西，而不仅仅是淫秽。这一点很好。淫秽是一个巨大的危险信号，但也有其他同样糟糕的事情。编辑答案以反映这一点。嗯，我不确定我会相信那些最关心评论中淫秽内容的人所写的代码，而不是那些清楚、写得好的评论-1为什么