需要有关方法的冗长命名的建议

Question

我正在编写一个用于创建几何形状的 API，但在命名我的方法时遇到了一些困难。

让我们看一个简单的例子：创建一个圆。 我们大多数人可能熟悉像 Graphics.drawEllipse(x, y, w, h) 这样的方法。 要绘制一个圆，您需要知道左上角的坐标以及圆的宽度和高度。

我的 API 旨在使开发人员能够轻松地使用各种信息绘制形状，而无需进行大量数学计算 - 这对于圆形来说很简单，但对于其他形状来说则更复杂。 例如，您还应该能够在给定圆心坐标和半径或左上角和右下角坐标的情况下绘制圆。

所以我有一个带有工厂方法的 Circle 类，例如： <代码>

Circle.createWithCenterAndRadius(cx, cy, r)
Circle.createWithBoundingBox(x1, y1, x2, y2)
Circle.createWithWidthAndHeight(x, y, w, h)

我觉得这里可能有一种“代码味道”，但我不确定。 一方面，这些工厂方法必然是描述性的。 另一方面，我可以预见这些方法名称会失去控制。 例如，我如何命名一个三角形工厂方法，该方法在给定一个点、一条边的长度、一个角度和另一条边的长度的情况下创建一个三角形？ Triangle.createWithPointSideAngleAndSide(x, y, side1, angle, side2)？ 难道这只是邪恶吗？

如果您要使用此 API，您可以接受这样的方法名称吗？ 您对如何使方法名称更合理有什么建议吗？

Answer 1

您可以将您的圆圈方法更改为

Circle.FromCenterAndRadius(...)
Circle.FromBoundingBox(...)
Circle.FromWidthAndHeight(...)

这意味着您正在以一种简洁的方式从不同的表示形式创建圆圈......

Answer 2

在任何不支持命名参数的语言中都可以。 如果语言支持命名参数，我更喜欢简短的 Create 并且只有明显的参数名称。

对于具有命名参数的语言，您可以：

Circle.Create(
   centerX = cx, 
   centerY = cy, 
   radius = r
);

另一个更复杂的选项是一个流畅的界面，例如（但这可能太多了）：

circleBuilder.Center(cx,cy).Radius(r)
circleBuilder.Center(x,y).Width(w).Height(y)
circleBuilder.BoundWith().Left(x1,y1).Right(x2,y2)

Center 返回仅允许 Radius 或 Width 的中间类的实例。 BoundWith 返回一个只允许 Left 的值。

Answer 3

我认为你的描述方法没有任何问题——它们很紧凑，并且准确地描述了正在发生的事情。 库的用户和维护程序员都不会怀疑您的方法的功能。

如果您确实担心暴露大量工厂方法（例如具有属性类的工厂方法），您也可以在这里应用一些设计模式。 您可以拥有一个具有 CenterX、CenterY、Radius、(bool)UseCenterX、(bool)UseCenterY 等属性的 CircleProperties 类，然后将其传递给公共工厂方法，该方法将确定要使用哪个（私有）工厂方法。

假设 C#：

var circleProperties = new CircleProperties()
{
   CenterX = 10,
   CenterY = -5,
   Radius = 8,
   UseCenterX = true,
   UseCenterY = true,
   UseCenterRadius = true
};

var circle = Circle.Create(circleProperties);

Answer 4

我的第一直觉是拥有更多类型，这将允许更直观的方法重载。

// instead of Circle.createWithCenterAndRadius(cx, cy, r)
Circle.create( new Point(cx,xy), r);

// instead of Circle.createWithBoundingBox(x1, y1, x2, y2)
Circle.create( new Point(x1,y1), new Point(x1,y1) );
// or even...
Circle.create( new Box(p1,p2));

// instead of Circle.createWithWidthAndHeight(x, y, w, h)
Circle.create( new Point(x,y), w, h);

除了 Point 之外，您还可以定义 Distance（这将允许使用不同的单位）

如果这种风格适合您，请考虑为什么需要工厂方法而不是构造函数。

Circle c = new Circle(new Point(cx,xy), r);

Answer 5

对于不支持命名参数的语言，将方法名称设置为非常简单的名称（例如 Circle.create），然后仅添加额外的输入标志字符串（例如“center”或“bounding”）会更干净吗？ ”）表明对于仅根据输入变量数量和类型难以区分的情况应如何解释输入值？ 这样做的缺点是，它需要方法内部的额外逻辑来处理不同类型的输入参数，并且还要求用户记住标志选项。

Answer 6

我将拥有方法 CreateTriangle 并让重载显示所需的不同信息。

例如

Circle.CreateCircle(cx, cy, r)
Circle.CreateCircle(point1, point2)
Circle.CreateCircle(point, width, height)

Answer 7

是的，这更像是一个元答案，但我建议您看看 苹果的可可。

Answer 8

你的直觉是正确的——以这种方式创造事物的整个模式是不确定的。

除非这些只使用一两次，否则它们会变得非常混乱。 如果您要创建一个包含 5 个圆形和 3 个三角形的形状，那将会很混乱。

除了简单示例之外的任何事情都可能最好通过某种数据驱动的实现来完成。

为了实现这些目的，使用字符串、散列或 XML 来定义形状可能非常有用。

但这完全取决于您期望如何使用它们。

我在 Java 中创建 Swing 控件时也遇到同样的问题。 您最终会得到一行又一行的“new Button()”，后面跟着一堆 .set 属性调用以及一行将值复制到对象（或添加侦听器）的代码，以及一行重置值..

这种样板文件永远不应该在代码中发生，因此我通常尝试找到一种用数据驱动它的方法，将控件动态绑定到对象 - 为此，基于描述性字符串的语言将非常有帮助。

Answer 9

我知道我知道。 对于 C/C++/Java 人员来说，这听起来完全疯狂，但问题中给出的示例和所有这些答案清楚地表明了 CamelCaseNaming 的约定到底是多么糟糕。

让我们再看一下原来的例子：

Circle.createWithCenterAndRadius(cx, cy, r)  
Circle.createWithBoundingBox(x1, y1, x2, y2)
Circle.createWithWidthAndHeight(x, y, w, h)

现在让我们摆脱驼峰式命名法

Circle.create_with_center_and_radius(cx, cy, r)  
Circle.create_with_bounding_box(x1, y1, x2, y2)
Circle.create_with_width_and_height(x, y, w, h)

这可能看起来非常陌生，但说实话：哪个版本更容易阅读？