c - ANSI C - 创建良好 API 接口(interface)的技巧

Question

我正在尝试创建一个易于正确使用且难以错误使用的 API。

假设您有一个函数“bool MyObject_SetLocalDateTime(MyObject *pMyObject, params...)”，它允许客户端以YYYY MM DD HH MM SS 格式设置日期和时间 > 格式:

MyObject *pMyObject = MyObject_Create();
...
MyObject_SetLocalDateTime(pMyObject, params...);
...
MyObject_Destroy(&pMyObject);

该功能的良好界面是什么？如果有任何有关如何使接口(interface)在 ANSI C(而不是 C++)中易于正确使用且难以错误使用的提示，我将不胜感激。

Answer 1

我首先要说的是决定什么是“正确”。严重地。

您希望输入最准确吗？您希望该功能不会失败吗？您想限制可输入的值吗？您可能需要考虑您所创建的内容的要求。

如果调用此函数，数据的格式是什么？它可能只是用户输入的字符串“YYYY MM DD HH MM SS”，那么也许最明智的做法是采用一个字符串并自己解析出这些值。当然，您的函数内部还有很多工作要做。

此外，如果您自己编写该函数，则可以对输入值和测试更加宽松，因为您可能知道预期的内容。如果您正在为一个操作系统创建一个函数，该操作系统将有数十万人使用这些 API，您将需要更明确地了解允许的内容，并在函数内对其进行测试。

根据您的情况最“正确”的内容，有多种方法可以指定您引用的简单函数。

bool MyObject_SetLocalDateTime(pMyObject, int YYYY, unsigned int MM, unsigned int DD, int HH, int MM, int SS);//返回值表示成功或失败。

但是，如果消费者为 MM 传递零怎么办？如果消费者传入 13 怎么办？你使用基数0(通常是C使用的)还是常规的1-12来表示月份(jan-dec)的数字，从人类月份的角度来看，这更有意义，但有点奇怪C 程序员的思维方式是什么？

对于日期和时间之类的内容，C 库对此有定义，这会让您更轻松。另外，由于 C 库已经这样做了，因此对于使用您的函数的其他用户来说，这可能看起来更自然。

您还需要定义“难以错误使用”的含义。再说一遍，我是认真的。也许您想为月份(和日期)创建一个枚举，然后将其传递而不是整数。这将使编译器对 API 进行额外的类型检查，但聪明的 API 使用者可能会转换为另一个值，因此不要认为您可以跳过对有效输入的测试。

在您的函数内，您需要验证输入值，无论它们以何种形式传递，以确保它们有效，检查您是否不允许 2 月有 30 日，并且允许 29 日二月一次，但每四年一次。日期和时间有很多隐藏的复杂性，因此明智的做法是依赖操作系统或运行时库中已开发的例程。