我很想听听你有哪些清理公共头文件的例程 分发给客户。
我想听听您的意见：
评论不适用于外部消费。一般来说，我喜欢保持文档关闭 这样的代码和 cmets 可能不是一个好主意来分享：
/**
* @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);
是否有任何工具可用于准备发布的一般标头或代码？
【问题讨论】：
对于涉及多个开发人员的任何项目以及该源代码的后续版本，您应该始终进行扫描（以及其他您不应该说的话，例如，“我的老板让我这样做this”、“这段代码太糟糕了”等）。此外，对 cmets 进行拼写检查可能会有所帮助，因为人们拼写错误的单词会损害您的可信度。
【讨论】：
请确保您的标头不会生成任何编译器警告。
【讨论】：
总是有人（最好不止一个）通过标题查找任何看起来不专业的内容。您可以先使用代码格式化程序和其他自动工具。
对于 cmets，让他们寻找任何不专业或试探性的东西。纠正拼写错误。确保它们是准确的。有一个标准的方式来格式化它们，并坚持下去。
检查所有标识符名称。它们应符合风格指南并具有专业名称。
确保所有必要的 cmets 都在那里。这包括顶部的版权和联系信息。想出一个记录类等的标准方法，并执行它。
基本上，在我看来，您希望您的标题看起来像是由没有创造力或幽默感的无人机制作的，但它们完全一致（有点像 CPA 的刻板印象）。 （这有点像在客户访问办公室时要求您的开发人员穿西装 - 如果客户看不到您的开发人员的真实情况，他们会更开心。）
【讨论】：
如果您有文档的编码标准/格式通常会更好，客户会在他们第一次创建代码时看到开发人员自己遵循，这样您就不会花时间在发布之前清理代码，例如现在。
此外，Visual Studio 和其他几个 IDE 有一个“自动格式化”选项，您可以在其中设置样式并将其应用于您的代码（制表符、空格等）。我认为这主要是您在这里所要求的。
【讨论】：
根据我的经验，定期自动清理内部使用的标头以供公众使用是一项艰巨的任务，而且绝对容易出错。最终，不一致的格式或不恰当的评论将不可避免地蔓延开来。
在许多情况下，您最好将所有内容包装到一个小而干净的界面中，其标题始终保持干净并尽可能注释；例如，对该文件的修改应经过特别仔细的审查过程。
【讨论】：
我对这个主题不是很熟悉，但是对于开源项目，您通常在标题顶部有许可和版权声明。这可以避免几个司法问题。
【讨论】：
与删除笨拙的 cmets 一样重要的是添加必要的 cmets。您可能需要添加的内容：
【讨论】：
生日，
在 C++ 中，我喜欢使用 Handle-Body idiom 将实现与公共接口尽可能地分离。
您还应该确保所有样板文件，例如版权声明，是一致的和最新的，例如今天发布的代码的版权不会在 2008 年到期。
在命名约定、格式、布局和类设计的所有公共头文件中保持一致，否则会给客户留下不专业的印象。
确保您的头文件中没有“使用”声明。滥用“使用” dec 可能会因无意的副作用而严重搞砸事情。
如前所述，确保您的标头不会生成任何警告。
最后。确保你有一些好的 API 文档来配合你的头文件。
不要像提供知名邮政编码查询产品的公司一样。 C API 的第一个版本带有极少的大量基于 Windows GUI 版本的文档。头文件仅由函数组成，其参数只有类型而没有名称。而且没有 cmets。
要弄清楚这些函数实际做了什么，唯一的方法是对提供的一个简单的查找示例程序进行逆向工程并对其进行逆向工程。
不过，在设法做到这一点后，我每年为 BBC 的有需要的孩子们节省了数万英镑，因为筹款包提供的地址比往年更可能是正确的！
【讨论】：