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

问题描述

我需要创建一个API，让我的客户的开发人员使用专用I2C模块，将被释放作为一个库（想想的.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你-header.h和code将干净编译，即使这是第一个或唯一的头，他们包括）。

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.

的添加的：亚当问我对并没有什么，只有开发者需要扩展。这意味着，例如，即使该内部功能可以使用一些结构类型，如果没有外部接口的采用该结构类型，则公共头不应包含结构类型的定义。它应该是在不分发（或仅与完整的源分布）一个私有头。它不应该被污染公共报头。这是很容易说，但它仅仅是浪费的空间一点点，这是准确的，但如果每个人都浪费一点空间和时间，则总的废物可以成为昂贵。

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屋！