java - (JCalc) 为计算库设计API时，类和方法的正确命名是什么

Question

我正在开发一个库，该库将使用流畅的 API 在 Java 中提供更轻松的编写和计算。 库已经实现了基本功能，现在我正在努力改进 API。

我遵循 http://theamiableapi.com/2012/01/16/java-api-design-checklist/ 给出的(大部分)指示

但是我对一些类、方法的命名仍然有一些疑问。 所以我有几个关于命名这些问题的问题。

1. 对于计算，有基本类 Calculator，对于执行计算，有方法 'calculate'。 “计算”或简化的“计算”哪个更合适

2. 计算器类能够跟踪计算的每一步， 现在我有这些方法:

   • setTrackSteps(boolean) 可以跟踪计算的每个步骤
   • getTrackedSteps() 返回 TrackedStep 对象中每个步骤的列表
   • hasTrackedStep 检查是否启用/禁用跟踪计算步骤 有人对这些名字有更好的建议吗？

3. Calculator.getTrackedSteps() 返回 TrackedStep 对象的列表。 TrackedSteps 是一个有点刺耳的名字。 所以我想找一个更好的名字？

4. 我将公共(public) API 与内部实现分离到内部包中。 在这个包中，我有带有静态方法的“Utils”类，我试图避免使用这个通用名称。 也许是 HelperUtils？ 我试图避免使用 Calc 或 Calculator 前缀，因为当最终用户使用某些 IDE 并开始编写 Cal.. 时，IDE 将提供几个以 Cal.. 开头的类，包括“Calc..Utils”

如果有人对 api 更感兴趣，可以访问 GitHub和来自 project webpage

Answer 1

有些人可能认为这是“主要基于意见”。鉴于您已有代码，并且想要对此发表(某种)意见，有些人可能会推荐您引用 CodeReview StackExchange 。然而，在 API 设计方面有一些常见的最佳实践，所以这可能没问题。不过，以下几点是稍微模糊的建议，您不应仅根据问答网站的一个答案做出决定。

<小时/>

1.:我同意 list 中提到的观点:

2.2.11. Avoid abbreviations

所以名称calculate应该是首选。无论如何，拥有 IDE 的人只需输入 .c...，然后按 CTRL+Space...

2.:根据 boolean 属性的常用约定，这些方法也可以称为 setTrackingSteps(boolean) 和 isTrackingSteps() 分别符合 list :

3.7.2. Start the name of methods returning Boolean properties with “is”, “can” or similar

3.7.3. Start the name of methods updating local properties with “set”

3.:我不确定你所说的“严厉”是什么意思。是否存在未跟踪的步骤？如果不是，该类型可以简单地称为 Step 而不是 TrackedStep。

4.:这个Utils类真的必须是public吗？如有疑问，请将其排除。 HelperUtils 这个名字看起来像是一个同义反复。无论如何，实际名称主要取决于该类中的方法有什么共同点。粗略浏览一下代码，我发现有两种方法:

public static boolean equals(Object objA, Object objB) {...}

public static Num[] toNums(Object... object) { ... }

根据这个类是否真的必须是公共(public)的，以及是否需要添加更多方法，到目前为止合适的名称可能只是Objects(另请参阅Guava Objects::equals)。这将允许看起来像散文的用法:

if (Objects.equal(objectA, objectB)) {
    Num nums[] = Objects.toNums(objectA, objectB);
    ... 
}

后一种方法也可以包含在名为 Nums 的类中，称为 Nums.fromObjects(...)。

<小时/>

顺便说一句:说到 API 设计，我绝对推荐 How to design a good API - and why it matters 的演讲。约书亚·布洛赫着。此外，您可能会找到 API Design Wiki有趣的是:它是由 NetBeans 的创始人和初始架构师 Jaroslav Tulach 创建的。