有意义的简洁方法命名准则

最近，我开始发布一个开源项目，虽然我是该库的唯一用户，但我并不关心名称，但知道我想为每种方法分配聪明的名称，以使其更易于学习，但我还需要使用简洁的名称，因此也易于编写。

我在考虑一些有关命名的准则，我知道许多准则只关心字母大小写或一些简单的注释。在这里，我正在寻找有意义但又简洁的命名准则。

例如，这可能是我所遵循的准则的一部分：

• 将现有项目添加到目标时，请使用添加；要创建新项目并将其添加到目标时，请使用创建。
• 要从目标中删除现有项目时，请使用“删除”；要永久删除项目时，请使用“删除”。
• 将AddXXX方法与RemoveXXX方法配对，并将CreateXXX方法与DeleteXXX方法配对，但不要混合使用。

如以上示例所示，我想找到一些在线资料，以帮助我找到符合英语语法和单词含义的命名方法和其他项目。

对于以英语为母语的人来说，以上指导可能是直观的，但对我来说，英语是我的第二语言，因此需要告知我这种情况。

命名。关于软件开发最困难的事情之一：）

当我命名时，这是我的优先事项：

• 遵循我的语言习惯用法。Ruby喜欢强调下划线。Javascript喜欢骆驼的情况。无论您使用哪种语言，都必须遵循约定。
• 显示API的意图。不是“ send_http_data”，而是“ post_twitter_status”
• 避免泄漏实施细节。说，在变量前面加上类型。
• 在不违反先前准则的情况下，请勿使用多余的字符。

显然，这是一种相当简单的方法。命名很细微。

为了进行进一步的研究，我建议您阅读《可读代码的艺术》，因为它在方法命名方面提供了一些出色的，简洁的建议。为了进行更多研究，我不能再高度推荐Bob Martin的Clean Code

在某些情况下，将名称的样式或约定编成代码的诱惑可能会导致当今被认为不习惯的习惯，例如使用匈牙利符号。简单的答案是忘记命名约定和样式，就好像它是要单独确定的一些单独的事情一样，而应该专注于根据其实际表示的名称来命名系统中的所有内容。如果您限制每个方法的功能，以使它仅在概念上做一件事，并且您的方法名实际上描述了该方法应该做的一件事，那么方法名自然就会变得简洁。

变量，字段，类和文件名是其他内容。我建议，如果变量名太长，那么您尝试要么过于详细地描述这些项目，要么它们代表了复杂的事物，应该分解为更小的部分，或者以更抽象的方式进行描述方式。

归根结底，您要避免使用丑陋的代码来占据整个行的名称，或者避免使用glib以至于抢走它们的价值。

对我来说，为某事找到好名字总是会回到将其视为必须证明其存在的理由的对象。问你自己：

• 类/方法/变量有什么作用，即它的主要用途是什么？
• 它需要传达什么特定的目的，即名称中必须包含什么基本部分？

大多数开发人员都会同意，在命名方面，可读性始终是最重要的。不要只是编写代码，以便在编写代码时就知道您的意思，而是编写代码，以便将来在某个时候第一次看代码的人无需过多思考就可以知道您的意思。您只需要编写一次代码，但是在其生命周期中，很可能必须对其进行多次编辑，甚至需要阅读多次。

代码应该是自我记录的，也就是说，您的命名应该使所做的事情显而易见。如果您需要解释代码行在注释中的作用，而重命名并不能对其进行足够的改进，则应认真考虑将该行重构为具有适当描述性名称的新方法，以便阅读原始方法，新方法调用描述了正在发生的事情。不要害怕拥有长名字；当然，您不应该用类/方法/变量名来写小说，但是我宁愿名称太长，描述性强也不要太短，我需要在幕后才能弄清楚它的作用。除了一些明显的例外（例如x / y坐标和常用的首字母缩写）外，请避免使用单字符名称和缩写。调用“ bkBtn”而不是“ backButton”

在您的语言允许的范围内，使您的代码看起来像英语句子。对象使用名词，方法使用动词。布尔方法通常以“ is”开头，但根据使用情况，还有许多其他选项可以更好地传达含义，例如“ can”，“ should”或“ does”。当然，并非所有语言都可以像Smalltalk一样出色，但是某些符号通常被理解为句子的一部分。我个人想尽可能多地采用其他语言的两种Smalltalk约定是，循环参数的名称以“ each”作为前缀，方法的参数以文章“ a”（或集合的“ an”或“ some”）作为前缀。 。这可能不是Java中的通用标准，欢迎任何人忽略此位，但是我发现这大大提高了代码的可读性。例如（Java中的示例）：

public boolean shouldConsiderAbbreviating(List<String> someNames) {
  for (String eachName : someNames) {
    if (isTooLong(eachName)) {
      return true;
    }
  }
  return false;
}

对于只有一点点Java知识的人来说，这应该是可读的，例如：

要确定是否应考虑缩写一些名称（字符串）的列表，遍历一些名称，并为每个名称确定名称是否太长；如果是这样，返回true；如果都不是太长，则返回false。

将上面的代码与仅命名参数strings和循环变量进行对比string，尤其是在更复杂的方法中。您必须仔细查看才能看到区别，而不是一眼看出名称的用法就很明显。

找到一个好的命名永远是更多因素之间的折衷。您将永远不会完全满意。

也就是说，即使您的母语不是那样，也要考虑英语是其编程语言标记形成的语言。使用类似英语的语法会使代码阅读更加“流畅”，因为每次找到关键字时都不会出现“阅读规则破损”的情况。

一般而言，请考虑类似object.method(parameters)的方案subject.verb(complements)。

如果必须支持通用编程，关键点是选择一组良好且一致的“动词”（尤其是在通用算法中需要使用的动词）。

关于名词，应根据其名称are（从概念上）命名类，而按其名称命名对象are for。

也就是说，介于两者之间list.add(component)并且component.add_to(list)喜欢第一者。一般而言，“主动及物”动词可以更好地表示针对其被动或反身对应物的动作。除非设计约束您。

不必担心方法名称的长度。确保方法名称清楚地反映了它们在做什么。这对其他任何事情都至关重要。如果您觉得方法名称太长，请使用同义词库找到一个表示相同意思的较短单词。例如，使用Find代替Retrieve。

同样重要的是您为课程选择的名称。这些在查看方法名称时提供了很多上下文。这样的方法签名：

public User Find(int userId);

比以下内容更容易理解：

public Person Find(int personId);

因为从类名获得的上下文User告诉程序员Find()要定位特定类型的人（系统的用户）。使用Person该类的版本没有为您提供任何上下文说明您为什么甚至需要首先使用该方法的情况。

查看您平台上的其他人是如何做到的-一些较大的公司甚至可能具有代码风格和命名准则。

一些平台更喜欢短名称（例如，在Win32 C API中_tcsstr是在字符串中查找字符串的功能-显而易见吗？），其他平台则出于可读性的考虑而简化（在Apple的Objective-C Cocoa框架中） ，将一个字符串中的子字符串替换为另一个字符串并以副本形式返回结果的方法称为stringByReplacingOccurrencesOfString: withString:）。我发现后者非常容易理解，而编写起来则稍难（尤其是代码完成）。

由于您读取代码的频率要比编写代码的频率高（对于开放源代码库而言，这双双正确），并且读取比编写更难，因此请针对读取进行优化。为简洁起见，只进行最后优化，并且在不影响清晰度的情况下尽可能地多地优化。

1. 假设使用英语，除非曾经使用此代码的每个开发人员都使用相同的非英语语言。

2. 研究公认的命名约定和样式。 您的指导原则应该清晰。样式因编程语言而异。

3. 命名没有什么可以做的，这将使您更容易理解代码中各个对象之间的关系。为此，您仍然需要写得很好的注释和文档。

1. 使用前缀。如果一堆方法用于执行相似的操作或可以某种方式组合在一起，则在其名称前放置一个公共前缀以显示这些方法的共同点。
2. 如果您想让其他人立即理解名称，请不要使用不清楚的缩写（在API命名中很重要）