6

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

我想听听您的意见的一些事情是：

评论不适用于外部消费。一般来说，我喜欢让文档靠近代码，这样的评论可能不是一个好主意：

/**
 * @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);

是否有任何工具可用于准备一般发布的标头或代码？

4

8 回答 8

14

在任何长时间涉及多个开发人员的任何项目以及该源代码的后续版本中，您都应该始终扫描脏话（以及您不应该说的其他内容，例如，“我的老板让我这样做”， “这段代码很糟糕”等）。此外，对评论进行拼写检查可能会有所帮助，因为人们拼写错误的单词会损害您的可信度。

于 2009-06-05T11:55:03.597 回答
11

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

于 2009-06-05T11:59:40.687 回答
3

总是让某人（最好不止一个）通过标题来寻找任何看起来不专业的东西。您可以先使用代码格式化程序和其他自动工具。

对于评论，让他们寻找任何不专业或暂定的内容。纠正拼写错误。确保它们是准确的。有一个标准的方式来格式化它们，并坚持下去。

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

确保所有必要的评论都在那里。这包括顶部的版权和联系信息。想出一个记录类等的标准方法，并执行它。

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

于 2009-06-05T14:56:51.653 回答
2

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

  • 版权/使用条款标题
  • 支持联系信息
  • 文档链接（如果在线提供）
  • 公共接口的文档（返回值、参数、前置和后置条件等）
  • 对暴露但不用于生产用途的功能/方法的警告
于 2009-06-05T14:23:24.373 回答
2

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

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

于 2009-06-05T13:25:37.597 回答
2

如果您有文档的编码标准/格式通常会更好，客户会在他们第一次创建代码时看到开发人员自己遵循，这样您就不会在发布之前花时间清理代码，例如现在。

此外，Visual Studio 和其他几个 IDE 有一个“自动格式化”选项，您可以在其中设置样式并将其应用于您的代码（制表符、空格等）。我认为这主要是你在这里要求的。

于 2009-06-05T12:03:30.337 回答
2

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

于 2009-06-05T12:10:38.183 回答
1

天，

在 C++ 中，我喜欢使用Handle-Body 习惯用法来尽可能地将实现与公共接口分离。

您还应该确保任何样板文件（例如版权声明）是一致的并且是最新的，例如今天发布的代码的版权不会在 2008 年到期。

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

确保头文件中没有“使用”声明。滥用“使用” dec's 可能会因无意的副作用而严重搞砸事情。

如前所述，请确保您的标头不会生成任何警告。

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

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

弄清楚这些函数实际做了什么的唯一方法是对提供的简单查找示例程序进行逆向工程并对其进行逆向工程。

尽管如此，在设法做到这一点之后，我每年为 BBC 的有需要的孩子们节省了数万英镑，因为为筹款包提供的地址比往年更有可能是正确的！

于 2009-06-05T13:02:42.150 回答