为我建议一个更好的 API 方法名称

Question

简介：

我正在开发一个 API，它提供对 Picasa、Flickr 和其他一些图像服务的访问。

我有一个 WebAlbum 类（它提供对嵌套照片、相册（如果允许）和一些元信息的访问。

我的 API 不仅允许用户阅读相册，还允许他们创建新相册。一般情况下，为了创建新相册，API 用户应使用工厂方法来创建相册，然后调用方法 WebGallery#addAlbum (newAlbum)。

但 Flickr 不允许创建空相册，它要求任何新相册中至少有一张预定义的照片（可能是为了制作漂亮的相册预览）。在 Flickr 术语中，第一张照片称为主照片。因此，为了为 Flickr 创建相册，用户应该使用工厂方法，然后将图像添加到新相册，然后调用 WebGallery#addAlbum (newAlbum)。

问题：

目前 WebAlbum 类有这个方法，

public interface WebAlbum {

   ...

   public boolean requiresPrimaryPhoto ();
}

我不能保留这个名称，因为 PrimaryPhoto 只是一个 Flickr 术语。我可以将其更改为

public interface WebAlbum {

   ...
   //with spaces: requires one added photo to create new album

   public boolean requiresOneAddedPhotoToCreateNewAlbum ();
}

请建议一个具有相同含义的较短名称。

Answer 1

布尔值 isEmptyAlbumAllowed

Answer 2

public boolean needDefault;

或者，更具描述性

public boolean needDefaultImg;

编辑
您应该问自己的另一个问题是该属性是否应该公开。如果您想让管理相册的体验在所有后端保持一致，那么您的图书馆可能可以在需要时提供默认图像。也许是您的应用程序的徽标。无论如何，用户不太可能长时间拥有空相册。

Answer 3

我会选择

public boolean requiresDefaultImage;

或

public boolean requiresAlbumImage;

Answer 4

我会使用像allowsEmptyAlbum或emptyAlbumPermission这样的东西

，也就是说，添加一个额外的方法意味着该类的用户需要知道这甚至可能是一个问题，并记住在添加相册之前进行检查。这可能是一个问题，因为大多数开发人员“希望快速完成工作”并且不知道服务之间的差异。

即使在文档中添加注释也是不够的，因为许多调用“addAlbum”的人永远不会阅读该方法的文档，因为它看起来很简单（有关详细信息，请参阅我的研究）。

理想情况下，您可以为每个服务创建不同的工厂（并在其中提供信息），或者，如果您必须使用单个 API，请找到一种优雅地失败的方法，或者添加占位符图像。

Answer 5

我认为你可以通过删除多余的专辑部分来使其更短。

public boolean canBeEmpty();

Answer 6

   public boolean requiresInitialPhoto ();

   public boolean doesOnePhotoExist ();

   public boolean needsOnePhoto ();

Answer 7

创建 FlickerWebAlbum 和 PicasaWebAlbum 类。它们中的每一个都代表每个提供商的特定行为。

Answer 8

对您的问题的简短回答：

boolean isDefaultPhotoRequired;

较长的答案：并非所有网络相册都共享默认照片要求，因此它是使用继承的完美候选者。将该行为移至 Flickr 特定子类。您可以执行类似将 defaultImage 的创建添加到 Flickr.init() 中的操作。