专业#include内容
我需要创建一个API，允许我的客户的开发人员使用将作为库发布的专有C模块（想想.lib或.so – 不是源代码）。
我想尽可能使标题符合开发人员（因此我不需要），遵循最佳实践并提供说明，示例，警告等方面的评论 。
我还应该从业务，技术和普通常识的角度考虑什么？
谢谢！
头文件本身应该干净整洁，可能接近最小。 它应该指向可以找到文档的位置。 它可能不应该包含完整的示例（尽管我自己的一些标题可以做到这一点）。 它应包括有关版权和许可的基本信息以及作者详细信息。 它应该只包含最终用户需要的东西 – 只有开发人员需要的东西。 它应该是独立的; 它应该包含使其工作所需的任何其他头文件（因此用户可以编写’ #include "your-header.h" ‘并且代码将干净地编译，即使这是它们包含的第一个或唯一的头部）。
补充 ：标题也应包括一些基本版本信息（文件修订号和修改日期，和/或产品发布版本号和发布日期）。 这有助于人们查看该软件的两个版本 – 并且成功的软件不止一次发布。
补充 ：亚当让我扩展“只有开发人员需要的东西”。 这意味着，例如，即使内部函数可能使用某种结构类型，如果没有外部接口使用该结构类型，则公共头不应包含该结构类型的定义。 它应该位于未分发的私有头中（或仅与完整源一起分发）。 它不应该污染公共标题。 人们很容易说“但它只是浪费了一点点空间”，这是准确的，但如果每个人都浪费了一点点空间和时间，那么浪费的总量就会变得昂贵。
关于公共标题的关键点是它应该包含库的用户（函数集）需要的所有内容，以及它们不需要的任何东西。
一种选择是使用（例如）Doxygen从头部生成API文档。 显然，您仍然会将代码与文档一起发送。
这给您带来两个好处：
1）你不必担心某些东西应该是“在文档中”还是只是“在标题中的注释中”，因为改变一个就像改变另一个一样容易。 所以一切都在文档中。
2）用户不太可能首先阅读您的头文件，因为他们可以合理地确信所有感兴趣的内容都在文档中。 但即使他们顽固不化“我不信任文档，我也会阅读代码”类型，然后他们仍然会看到你希望他们看到的一切。
自动生成的API文档的缺点是它们可能是搜索的噩梦，所以IMO值得花更多的精力来编写真正好的“入门”文档。 这可能是也可能不是生成的API文档的一部分，具体取决于您的喜好。 对于一个小型API，只需按照“逻辑”而不是按字母或源顺序列出所有函数的列表，根据它们的用途而不是它们的用途进行描述，可以更容易地进入API文档。 通过“逻辑”，我的意思是首先列出常用函数，按照客户端调用它们的顺序，使用“做同样的事情”的替代方法（例如发送和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放在标题中。 这将允许一些维护程序员在未来几年内访问文档，即使原件已丢失。