问题标签 [api-design]

我有一些代码在 C++ 中有一个动态类系统，它有一个名为 GetClassName() 的成员，这是一个可以想象的相当无害的名称。然而，当包含在一个带有 Windows 标头的大型项目中时，一切都乱了套。显然，Windows 使用了 #define GetClassName（GetClassNameA 或 GetClassNameW），它搞砸了一切，我的虚拟调用树变得一团糟，让我在黑暗中愚蠢的编译器调试中浪费了一天，试图找出问题所在。

因此，除了我在诅咒微软为#define 使用如此可怕的容易冲突的名称（我的意思是应该诚实地为此开枪！）之外，我要求 3 个目的。

1. GetClassName() 的另一个好名字是什么？
2. 有没有办法解决这个问题，所以将来我的代码库的其他开发人员不会遭受类似的命运
3. 当其他人遇到这种类似莫名其妙的错误时，为了后代

我最近正在观看有关如何创建流畅的 DSL的网络广播，我不得不承认，我不明白为什么要使用这种方法（至少对于给定的示例）。

网络广播展示了一个图像大小调整类，它允许您使用以下语法（使用 C#）指定输入图像、调整大小并将其保存到输出文件：

我不明白这比采用一些参数的“传统”方法更好：

从可用性的角度来看，这似乎更容易使用，因为它清楚地告诉您方法期望作为输入的内容。相比之下，使用流畅的界面，没有什么能阻止您省略/忘记参数/方法调用，例如：

那么关于我的问题：

1 -有什么方法可以提高流畅界面的可用性（即告诉用户他应该做什么）？

2 -这种流畅的接口方法是否只是 C# 中不存在的命名方法参数的替代品？命名参数是否会使流利的接口过时，例如类似的objective-C提供的东西：

3 -流畅的界面是否仅仅因为它们目前很流行而被过度使用？

4 -或者它只是为网络广播选择的一个坏例子？在这种情况下，请告诉我这种方法的优点是什么，在哪里使用它有意义。

顺便说一句：我知道 jquery，并且看到它使事情变得多么容易，所以我不是在寻找关于那个或其他现有示例的评论。

我更多的是寻找一些（一般的）评论来帮助我理解（例如）何时实现一个流畅的接口（而不是一个经典的类库），以及在实现一个时要注意什么。

将新成员函数添加到 d 指针类定义中会破坏二进制兼容性吗？

例如，与原始定义相比，下面的新定义会破坏二进制兼容性吗？（附带问题，是否有工具可以告诉我新的 .so 与旧的 .so 相比是否会破坏二进制兼容性？如果没有，我该如何手动检查？）

原来的：

新的：

仅供参考：我知道 d 指针类应该在 cc 文件而不是标题中指定。上面的示例旨在关注二进制兼容性问题。

我有一个包裹

还有这些

该软件包的用户需要 Player，但为了在不破坏它的情况下使用该软件包，我要求他们永远不要直接扩展 Player。相反，他们应该扩展提供的子类之一。

问题：我应该如何防止用户直接扩展 Player？

我正在寻找一种方法来明确表明该禁令是有意的。

我真的有两个问题：

1) 你什么时候会使用包私有接口？

2）有没有办法让一个公共接口在其包外实现而关闭？

我鄙视使用过度设计的 API，这些 API 不会让简单的事情变得简单。尽管如此，我正在为一个开源库设计一个 API，我开始觉得自己掉进了过度工程的陷阱。我真的无法确定，因为当然，我写了这该死的东西，所以它的工作原理对我来说比其他任何人都更明显。从开发人员的角度来看，有哪些警告信号表明您的 API 可能被过度设计？

谁能想到一个很好的解释，即对话的结果在 WPF 中是一个可以为空的布尔值？这一直让我感到困惑。在 WinForms 中，它是一种枚举类型，这对我来说更有意义。

如果你可以在 Cocoa 中添加任何东西，那会是什么？您会说 Cocoa 中是否缺少任何主要或次要功能。也许因为框架中的一个遗漏，你不得不一遍又一遍地发明一个轮子？

我正在学习 Objective-C，并且有 C/C++ 背景。

• 在面向对象的 C++ 中，您总是需要在定义（实现）方法之前声明您的方法，即使它是在父类中声明的。

• 在过程风格的 C、IIRC 中，您可以只定义一个函数，只要它仅从稍后出现在文件中的同一编译单元（即同一文件）中的其他东西调用（好吧，提供您不会在其他地方用“extern”声明它）。

• 现在，在 Objective-C 中，您似乎只需要在头文件中声明选择器（如果它们将被外部使用），并且您可以在 .m 文件中很好地构建选择器，并在其中调用它们.m 文件。此外，似乎从未（重新）定义委托方法或继承方法。

我在正确的轨道上吗？什么时候需要在 Objective-C 中定义选择器？

注意：虽然我的特定上下文是 Objective-C，但我的问题实际上超越了编程语言的选择。此外，我将其标记为“主观”，因为否则肯定有人会抱怨，但我个人认为这几乎完全是客观的。另外，我知道这个相关的 SO question，但由于这是一个更大的问题，我认为最好将其作为一个单独的问题。请不要在没有完全阅读和理解的情况下批评这个问题。谢谢！

我们大多数人都熟悉存储键值关联的字典抽象数据类型，根据我们选择的语言，我们是否将其称为映射、字典、关联数组、哈希等。字典的简单定义可以概括为三个属性：

1. 通过键访问值（而不是通过索引，如数组）。
2. 每个键都与一个值相关联。
3. 每个键必须是唯一的。

任何其他属性都可以说是针对特定目的的便利或专业化。例如，某些语言（尤其是 PHP 和 Python 等脚本语言）模糊了字典和数组之间的界限，并且确实为字典提供了排序。尽管这很有用，但这样的添加并不是字典的基本特征。在纯粹意义上，字典的实际实现细节是无关紧要的。

对于我的问题，最重要的观察是未定义枚举键的顺序- 字典可以以它认为最方便的任何顺序提供键，并且由客户根据需要组织它们。

我创建了强制特定键排序的自定义字典，包括自然排序顺序（基于对象比较）和插入顺序。很明显，将前者命名为SortedDictionary上的某个变体（我实际上已经实现了），但后者的问题更大。我见过LinkedHashMap和LinkedMap (Java)、OrderedDictionary (.NET)、OrderedDictionary (Flash)、OrderedDict (Python) 和OrderedDictionary (Objective-C)。其中一些更成熟，一些更概念验证。

LinkedHashMap是根据 Java 集合传统中的实现来命名的——“linked”是因为它使用双向链表来跟踪插入顺序，而“hash”是因为它是 HashMap 的子类。除了用户不需要担心这一点之外，类名甚至没有真正表明它的作用。使用有序似乎是现有代码之间的共识，但关于这个主题的网络搜索也揭示了“有序”和“排序”之间的可以理解的混淆，我也有同感。.NET 实现甚至对明显的误称有评论，并建议它应该改为“IndexedDictionary”，因为您可以在排序的特定点检索和插入对象。

我正在设计一个框架和 API，我想尽可能智能地命名这个类。从我的角度来看，索引可能会起作用（取决于人们如何解释它，并基于字典的广告功能），排序不精确并且有太多混淆的可能性，并且链接“是正确的”（向 Monty Python 道歉）。;-)

作为用户，什么名称对您来说最有意义？是否有一个特定的名称可以准确地说明该类的功能？（如果合适的话，我不反对使用稍长一些的名称，例如 InsertionOrderDictionary。）

编辑：另一个很大的可能性（在我下面的回答中讨论）是IndexedDictionary。我不太喜欢“插入顺序”，因为如果您允许用户在特定索引处插入键、重新排序键等，这没有任何意义。