我正在开发库,它将使用流畅的API提供更轻松的Java编写和计算功能。
库已经实现了基本功能,现在我正在努力改进API。
我遵循http://theamiableapi.com/2012/01/16/java-api-design-checklist/给出的(大部分)指令
但是在命名某些类,方法时我仍然有一些疑问。
所以我有几个关于命名这些问题。
为了进行计算,有一个基本类Calculator,对于执行计算,有方法'calculate'。
更可取的名称是“计算”或简化的“计算”
计算器类可以跟踪计算的每个步骤,
现在我有那些方法:
setTrackSteps(boolean)允许跟踪计算的每个步骤
getTrackedSteps()返回TrackedStep对象中每个步骤的列表
hasTrackedStep检查是否启用/禁用跟踪计算步骤
有人对这些名字有更好的建议吗?
Calculator.getTrackedSteps()返回对象TrackedStep的列表。
TrackedSteps有点苛刻。
所以我想找一个更好的名字?
我将带有内部实现的公共API分离到内部包中。
在这个软件包中,我有带有静态方法的'Utils'类,并且我试图避免使用该通用名称。
也许是HelperUtils?
我试图避免使用Calc或Calculator前缀,因为当最终用户使用某些IDE并开始编写Cal .. IDE会提供一些以Cal ..开头的类,包括“ Calc..Utils”
如果有人对api更感兴趣,可以从GitHub和project webpage获得
最佳答案
有些人可能会认为这是“基于主要意见”。鉴于您已有代码,并希望对此发表意见(一些),因此某些人可能会将您引荐至CodeReview StackExchange。但是,关于API设计,有一些通用的最佳实践,因此可能没问题。但是,以下几点是含糊的建议,您不应仅根据问答站点的一个答案来做出决定。
1 .:我同意清单中提到的观点:
2.2.11。避免缩写
因此,应首选名称calculate
。使用IDE的人无论如何都只需键入.c...
,然后按CTRL + Space ...
2 .:根据用于布尔属性的常规约定,这些方法也可以分别称为setTrackingSteps(boolean)
和isTrackingSteps()
,这与检查表一致:
3.7.2。以“ is”,“ can”或类似名称开头的方法返回布尔属性的名称
3.7.3。以“ set”开头的方法名称更新本地属性
3 .:我不确定您所说的“苛刻”是什么意思。是否存在未跟踪的步骤?如果不是,则可以将类型简称为Step
而不是TrackedStep
。
4 .:此Utils
类是否真的必须是public
?如有疑问,请不要理会。名称HelperUtils
似乎是重言式。无论如何,实际名称主要取决于此类中的方法的共同点。简短地看一下代码,我看到了两种方法:
public static boolean equals(Object objA, Object objB) {...}
public static Num[] toNums(Object... object) { ... }
根据此类是否真的必须是公共的,以及是否需要添加其他方法,到目前为止,适当的名称可能只是
Objects
(另请参见Guava Objects::equals)。这将允许使用看起来像散文的用法:if (Objects.equal(objectA, objectB)) {
Num nums[] = Objects.toNums(objectA, objectB);
...
}
后一种方法也可以包含在称为
Nums
的类中。顺便说一句:关于API设计,我绝对可以推荐Joshua Bloch的有关How to design a good API - and why it matters的讨论。此外,您可能会发现API Design Wiki有趣:它是NetBeans的创始人和初始架构师Jaroslav Tulach创建的。