专业 #include 内容 [英] Professional #include contents

问题描述

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

I need to create an API that will allow my customer's developers to use a proprietary C module that will be released as a library (think .lib or .so -- not source).

我希望标题尽可能对开发人员友好(所以我不需要这样做)，遵循最佳实践并提供带有描述、示例、警告等的评论.

I'd like to make the header as developer-friendly as possible (so I won't need to be), following best practices and providing comments with descriptions, examples, caveats, etc.

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

What else should I consider from business, technical, and plain common-sense perspectives?

谢谢！

推荐答案

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

The header file itself should be clean and tidy and probably close to minimal. It should point to where the documentation can be found. It probably shouldn't include complete examples (notwithstanding some of my own headers that do that). It should include basic information about the copyright and licence and author details. It should only contain stuff that end users need - nothing that only the developers need. It should be self-contained; it should include any other headers necessary to make it work (so the user can write '#include "your-header.h"' and the code will compile cleanly, even if that's the first or only header they include).

已添加:标题还应包含一些基本版本信息(文件修订号和修改日期，和/或产品发布版本号和发布日期).这有助于人们查看软件的两个版本——成功的软件发布不止一次.

Added: The header should include some basic version information too (file revision number and modification date, and/or the product release version number and release date). This helps people looking at two releases of the software -- and successful software is released more than once.

添加:Adam 要求我扩展并且没有只有开发人员需要的东西".这意味着，例如，即使内部函数可能使用某种结构类型，如果没有任何外部接口使用该结构类型，则公共标头不应包含该结构类型的定义.它应该位于未分发(或仅随完整源代码分发)的私有标头中.它不应该污染公共标头.说但它只是浪费了一点空间"很诱人，这是准确的，但如果每个人都浪费一点空间和时间，那么总浪费就会变得昂贵.

Added: Adam asked me to expand on "and nothing that only the developers need". That means, for example, that even though the internal functions may use some structure type, if none of the external interfaces uses that structure type, then the public header should not contain a definition of that structure type. It should be in a private header that is not distributed (or is only distributed with the complete source). It should not be polluting the public header. It is tempting to say "but it is only a little bit of wasted space", and it is accurate, but if everyone wastes a little space and time, then the total waste can become expensive.

公共头文件的关键在于它应该包含库(函数集)用户需要的所有内容，而没有他们不需要的内容.

The key point about the public header is that it should contain everything that the user of the library (set of functions) needs, and nothing that they do not need.

这篇关于专业 #include 内容的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！