97-things-every-programmer-should-know-19: 设计API不能只注重方便

关于设计一个好API的重要性和挑战性已经说过很多次了，首次设计API就正确很难，更难的是后期要持续更改它，就像抚养小孩一样。大多数有经验的程序员已经意识到一个好的API需要遵循一致的抽象层次，表现出一致性和对称性，但需要意识到指导原则不会自动转化为正确的结果。

避免空谈，我选择一个特定的API设计策略： 一个反复遇到的问题-参数的便利性。通常有以下见解：

• 如果另一个方法跟当前方法几乎相同为什么要新建一个方法？直接加个开关即可。
• 如果第二个参数是以".txt"结尾，这个方法自动判断第一个参数是文件名，所以不需要两个方法。

当这样做了之后，这样的参数会造成API的可读性降低，一个方法的执行如下：

parser.processNodes(text, false);

这样的写法如果不深入了解细节几乎毫无意义，或至少需要阅读文档。这个方法的实现是为了接口实现者方便而非接口调用者。

API应该隐藏底层的复杂性，所以良好的API需要付出更多的努力。一个大方法当然更容易写，但它会更易使用吗？

小结

一个API应该能提供表达性的语言，这并不意味着它应该只提供一个方法或动词，多样化的词汇使我们能够表达微妙的含义。一个一致的，经过深思熟虑的API词汇对下一层更易表达和理解。更重要的是有利于其他程序员以你想不到方式组合你的API。下次当您想将一些东西组合在一个API方法中时，要抑制住自己的冲动，即使这个组合看起来真的很方便。