•  07-07-2019
  •  | 
  •  

题

我需要创建一个API，允许我的客户的开发人员使用将作为库发布的专有C模块（想想 .lib 或 .so - - 不是来源。）

我希望尽可能使标题符合开发人员（因此我不需要），遵循最佳做法并提供说明，示例，警告，等的注释。

我还应该从业务，技术和普通常识的角度考虑什么？

谢谢！

有帮助吗？

解决方案

头文件本身应该干净整洁，可能接近最小。它应指向可以找到文档的位置。它可能不应该包含完整的示例（尽管我自己的一些标题可以做到这一点）。它应包括有关版权和许可的基本信息以及作者详细信息。它应该只包含最终用户需要的东西 - 只有开发人员需要的东西。它应该是独立的;它应该包含使其工作所需的任何其他头文件（因此用户可以编写' #include＆quot; your-header.h＆quot; '并且代码将干净地编译，即使这是第一个或唯一的标题包括）。

已添加：标题也应包含一些基本版本信息（文件修订号和修改日期，和/或产品发布版本号和发布日期）。这有助于人们查看该软件的两个版本 - 并且成功的软件不止一次发布。

已添加：Adam要求我展开“并没有只有开发人员需要的东西”。这意味着，例如，即使内部函数可能使用某种结构类型，如果没有外部接口使用该结构类型，则公共头不应包含该结构类型的定义。它应该位于未分发的私有头中（或仅与完整源一起分发）。它不应该污染公共标题。很有可能说“但它只是一点点浪费的空间”，而且它是准确的，但如果每个人浪费一点点空间和时间，那么总浪费可能变得昂贵。

关于公共标题的关键点是它应该包含库的用户（函数集）所需的所有内容，以及它们不需要的任何内容。

其他提示

一种选择是使用（例如）Doxygen从头文件生成API文档。显然，你仍然会将文档与代码一起发送。

这给你带来两个好处：

1）你不必担心某些事情是否应该“在文件中”。或者只是“在标题中的评论中”，因为改变一个就像改变另一个一样容易。所以一切都在文档中。

2）用户不太可能首先阅读您的头文件，因为他们可以合理地确信所有感兴趣的内容都在文档中。但即使他们很顽固，“我也不相信文档，我会阅读代码”。类型，然后他们仍然看到你想让他们看到的一切。

自动生成的API文档的缺点是它们可能成为搜索的噩梦，所以IMO值得付出额外的努力来编写真正好的“介绍性”文档。文档。这可能是也可能不是生成的API文档的一部分，具体取决于您的喜好。对于小型API，只需列出“逻辑”中的所有函数。而不是按字母顺序或源顺序描述，根据他们 的内容而不是他们的内容进行描述，可以更容易地进入API文档。通过“逻辑”，我的意思是首先列出常用功能，按照客户端称之为的顺序，使用“做同样的事情”的替代方案。 （例如send和sendTo for socket）组合在一起。然后列出不太常用的函数，最后列出高级用户和不寻常用例的模糊内容。

这种方法的一个主要难点，可能是一个显示阻止，是根据您的组织，您可能有一个文档团队，他们可能无法编辑标题。最好的情况是，他们复制 - 编辑你已完成的工作，然后进行更改并反馈。最糟糕的情况是整个想法停滞不前，因为“只有文档团队应该编写面向客户的文档，并且它必须采用标准格式，并且我们不能使Doxygen输出格式化”。

至于“你应该考虑什么？” - 你已经说过你会遵循最佳实践，所以很难添加很多： - ）

请相当请确保您没有（重新）定义可能在其他地方定义的符号。我并不仅仅指标准名称，请在公共标题中声明/定义的所有符号前缀为特定字符串，并避免任何其他人可能曾经使用的任何名称。

我在“专业”中看到太多像这样的疯狂之后说这个。公开标题：

typedef unsigned short uchar;

其他人提到了文档问题，所以我会远离那些:-P。首先，确保你有理智的包括警卫。我个人倾向于：

FILENAME_20081110_H _ ，基本上是全部大写的文件名，然后是完整日期，这有助于确保它足够独特，即使树中有另一个具有相同名称的标题。 （例如，您可以想象两个config.h包含在2个不同的lib目录中，其中有使用 CONFIG_H _ 或类似的东西，因此存在冲突。无论你选择什么都没关系，所以因为它可能是独特的。

此外，如果任何机会在c ++项目中使用此标头，请将标题包装在以下块中：

#ifdef __cplusplus
extern "C" {
#endif

/* your stuff */

#ifdef __cplusplus
}
#endif

这样可以节省一些带有名称重整问题的麻烦，并使它们不必在外部用这些包裹它们。

考虑实际编写单独的文档。我认为man / info页面提供了一个很好的例子，说明API文档应该是什么样的。

除了任何船只之外，考虑将文档放在网上，并将URL放在标题中。这将允许一些维护程序员在未来几年内访问文档，即使原件已丢失。

许可以下： CC-BY-SA 和 归因
不隶属于 StackOverflow
scroll top