51. 仔细设计方法签名

这一条目是 API 设计提示的大杂烩，但它们本身并足以设立一个单独的条目。综合起来，这些设计提示将帮助你更容易地学习和使用 API，并且更不容易出错。

仔细选择方法名名称。名称应始终遵守标准命名约定（详见第 68 条）。你的主要目标应该是选择与同一包中的其他名称一致且易于理解的名称。其次是应该是选择与更广泛的共识一致的名称。避免使用较长的方法名。如果有疑问，可以从 Java 类库 API 中寻求指导。尽管类库中也存在许多不一致之处（考虑到这些类库的规模和范围，这是不可避免的），也提供了相当客观的认可和共识。

不要过分地提供方便的方法。每种方法都应该“尽其所能”。太多的方法使得类难以学习、使用、文档化、测试和维护。对于接口更是如此，在接口中，太多的方法使实现者和用户的工作变得复杂。对于类或接口支持的每个操作，提供一个功能完整的方法。只有在经常使用时，才考虑提供「快捷方式（shortcut）」。如果有疑问，请将其删除。

避免过长的参数列表。目标是四个或更少的参数。大多数程序员不能记住更长的参数列表。如果你的许多方法超过了这个限制，如果未经常引用其文档的情况下，那么你的 API 将无法使用。现代 IDE 编辑器会提供帮助，但是使用简短的参数列表仍然会更好。相同类型参数的长序列尤其有害。用户不仅不能记住参数的顺序，而且当他们意外地弄错参数顺序时，他们的程序仍然会编译和运行。只是不会按照作者的意图去执行。

有三种技术可以缩短过长的参数列表。一种方法是将方法分解为多个方法，每个方法只需要参数的一个子集。如果不小心，这可能会导致太多方法，但它也可以通过增加正交性（orthogonality）来减少方法个数。例如，考虑 java.util.List 接口。它没有提供查找子列表中元素的第一个或最后一个索引的方法，这两个索引都需要三个参数。相反，它提供了 subList 方法，该方法接受两个参数并返回子列表的视图。此方法可以与 indexOf 或 lastIndexOf 方法结合使用，这两个方法都有一个参数，以生成所需的功能。此外，subList 方法可以与在 List 实例上操作的任何方法组合，以对子列表执行任意计算。得到的 API 具有非常高的功率重量 ( power-to-weight) 比。

缩短过长参数列表的第二种技术是创建辅助类来保存参数组。这些辅助类通常是静态成员类 (条目 24)。如果看到一个频繁出现的参数序列表示某个不同的实体，建议使用这种技术。例如，假设正在编写一个表示纸牌游戏的类，并且发现不断地传递一个由两个参数组成的序列，这些参数表示纸牌的点数和花色。如果添加一个辅助类来表示卡片，并用辅助类的单个参数替换参数序列的每次出现，那么 API 和类的内部结构可能会受益。

结合前两个方面的第三种技术是，从对象构造到方法调用采用 Builder 模式 (条目 2)。如果你有一个方法有许多参数，特别是其中一些是可选的，那么可以定义一个对象来表示所有的参数，并允许客户端在这个对象上进行多个「setter」调用，每次设置一个参数或较小相关的组。设置好所需的参数后，客户端调用对象的「execute」方法，该方法对参数进行最后的有效性检查，并执行实际的计算。

对于参数类型，优先选择接口而不是类（详见第 64 条）。如果有一个合适的接口来定义一个参数，那么使用它来支持一个实现该接口的类。例如，没有理由在编写方法时使用 HashMap 作为输入参数，相反，而是使用 Map 作为参数，这允许传入 HashMap、TreeMap、ConcurrentHashMap、TreeMap 的子 Map（submap）或任何尚未编写的 Map 实现。通过使用的类而不是接口，就把客户端限制在特定的实现中，如果输入数据碰巧以其他形式存在，则强制执行不必要的、代价高昂的复制操作。

与布尔型参数相比，优先使用两个元素枚举类型，除非布尔型参数的含义在方法名中是明确的。枚举类型使代码更容易阅读和编写。此外，它们还可以方便地在以后添加更多选项。例如，你可能有一个 Thermometer 类型的静态工厂方法，这个方法的签名是以下这个枚举：

public enum TemperatureScale { FAHRENHEIT, CELSIUS }

Thermometer.newInstance(TemperatureScale.CELSIUS) 不仅比 Thermometer.newInstance(true) 更有意义，而且可以在将来的版本中将KELVIN添加到 TemperatureScale 中，而无需向 Thermometer 添加新的静态工厂。此外，还可以将温度刻度（temperature-scale）依赖关系重构为枚举常量的方法（详见第 34 条）。例如，每个刻度常量可以有一个采用 double 值并将其转换为 Celsius 的方法。

Effective-Java 仔细设计方法签名相关推荐

Effective Java 阅读笔记——方法
38:检查参数的有效性每当编写方法或者构造器的时候,应该考虑它的参数有哪些限制,在方法的开头处对参数进行检查,并且把这些限制写入文档. 注意: 对于公有方法,应该使用@throws标签在文档中说明违 ...
一句话给大家阐明 java中的方法签名！！！！Java中什么是方法签名
如题:what is method signature in java? answer:Definition: Two of the components of a method declaratio ...
Java中的方法签名
这几天不知道怎么了,总是碰到各种各样的NoSuchMethodException异常,但是Java为了方便值给了我们方法的方法签名,这对于刚接触的程序猿来说貌似有点蛋疼.今天从网上好好的百度/goog ...
java已被弱化签名,高效Java第四十条建议：谨慎设计方法签名
作用有助于设计易于学习和使用的API. 如何做--谨慎地选择方法的名称 1.选择易于理解的,并且与同一个包中的其他名称风格一致的名称. 2.选择与大众认可的名称相一致的名称. 如何做--不要过于追求 ...
谨慎设计方法签名（40）
2019独角兽企业重金招聘Python工程师标准>>> 本条目是若干API 设计技巧的总结: 1.谨慎选择方法的名称始终遵循标准的命名习惯易于理解,与同包的其他名称保持一致风格 ...
花了我一个晚上浓缩了一整套阿里资深技术专家设计教程整理出的java架构设计方法
最近学习了阿里资深技术专家设计教程,颇有收获,总结一下. 1 基本概念和目的相关资料领取架构设计的目的是为了解决系统复杂度带来的问题,并不是要面面俱到,不需要每个架构都具备高性能.高可用.高扩 ...
一文简单理解《Effective Java》建议
考虑用静态工厂方法替代构造方法传统的获取一个对象实例,通常是通过构造方法,new一个对象:不同数量的入参,会有不同的构造方法: 例如,统一的返回结果类,传统方式(伪代码)如下: //成功 retur ...
Effective Java读书笔记六：方法
第38条:检查参数的有效性绝大多数方法和构造器对于传递给它们的参数值都会有些限制.比如,索引值必须大于等于0,且不能超过其最大值,对象不能为null等.这样就可以在导致错误的源头将错误捕获,从而避免 ...
写出一下Java方法对应的签名_Java中的方法签名是否包含其返回类型？
Java类/接口中的方法签名是否包括其返回类型? 例: Java是否知道这两种方法之间的区别: public class Foo { public int myMethod(int param) { ...

Effective-Java 仔细设计方法签名

51. 仔细设计方法签名

Effective-Java 仔细设计方法签名相关推荐

最新文章

热门文章