[Javascript] 编程实践之1: Google的Javascript代码风格6：命名规范

6 命名规范

6.1 所有标识符的通用规则

标识符仅使用ASCII字母和数字，并且在以下少数情况下使用下划线，并且很少使用（当诸如Angular之类的框架要求时）美元符号。

在合理的范围内，尽可能给出描述性的名称。 不必担心节省水平空间，因为让新读者立即理解您的代码更为重要。 不要使用项目外部读者不清楚或不熟悉的缩写，也不要通过删除单词中的字母来缩写。

例如：

errorCount          // No abbreviation.
dnsConnectionIndex  // Most people know what "DNS" stands for.
referrerUrl         // Ditto for "URL".
customerId          // "Id" is both ubiquitous and unlikely to be misunderstood.

不允许：

n                   // Meaningless.
nErr                // Ambiguous abbreviation.
nCompConns          // Ambiguous abbreviation.
wgcConnections      // Only your group knows what this stands for.
pcReader            // Lots of things can be abbreviated "pc".
cstmrId             // Deletes internal letters.
kSecondsPerDay      // Do not use Hungarian notation.

6.2 标识符类型规则

6.2.1 Package命名

Package名称均为lowerCamelCase。 例如，my.exampleCode.deepSpace，而不是my.examplecode.deepspace或my.example_code.deep_space。

6.2.2 Class命名

类，接口，记录和typedef名称用UpperCamelCase编写。 未导出的类只不过是本地类：它们没有标记为@private，因此不用下划线来命名。

类型名称通常是名词或名词短语。 例如，Request，ImmutableList或VisibilityMode。 此外，有时接口名称可能是形容词或形容词短语（例如，Readable）。

6.2.3 Method命名

方法名称写在lowerCamelCase中。 @private方法的名称必须以结尾的下划线结尾。

方法名称通常是动词或动词短语。 例如，sendMessage或stop_。 永远不需要属性的getter和setter方法，但是如果使用它们，则应将其命名为getFoo（对于布尔值，可以选择命名为isFoo或hasFoo），对于setter则命名为setFoo(value)。

下划线也可能出现在JsUnit测试方法名称中，以分隔名称的逻辑组成部分。 一种典型的模式是test <MethodUnderTest>__<expectedOutcome>，例如testPop_emptyStack_throws。 没有一种命名测试方法的正确方法。

6.2.4 Enum命名

枚举名称是用UpperCamelCase编写的，类似于类，通常应为单数名词。 枚举中的各个项目以CONSTANT_CASE命名。

6.2.5 Constant命名

常量名称使用CONSTANT_CASE：所有大写字母，单词之间用下划线分隔。 没有必要使用结尾的下划线来命名常量，因为私有静态属性可以由（隐式私有）模块本地代替。

6.2.5.1 “constant”的定义

每个常量都是@const静态属性或模块本地const声明，但并非所有@const静态属性和模块本地consts都是常量。 在选择常量大小写之前，请考虑该字段是否真的像一个深不可更改的常量。 例如，如果该实例的可观察状态中的任何一个可以更改，则几乎可以肯定它不是常数。 仅企图从不改变对象通常是不够的。

例子：

// Constants
const NUMBER = 5;
/** @const */ exports.NAMES = ImmutableList.of('Ed', 'Ann');
/** @enum */ exports.SomeEnum = { ENUM_CONSTANT: 'value' };

// Not constants
let letVariable = 'non-const';
class MyClass { constructor() { /** @const {string} */ this.nonStatic = 'non-static'; } };
/** @type {string} */ MyClass.staticButMutable = 'not @const, can be reassigned';
const /** Set<string> */ mutableCollection = new Set();
const /** ImmutableSet<SomeMutableType> */ mutableElements = ImmutableSet.of(mutable);
const Foo = goog.require('my.Foo');  // mirrors imported name
const logger = log.getLogger('loggers.are.not.immutable');

通常情况下，“constant”的名称为名词或者名词短语。

6.2.5.2 本地别名

只要本地别名提高了标准名称的可读性，就应使用本地别名。 遵循与goog.requires（3.6 goog.require和goog.requireType语句）相同的规则，并保留别名的最后一部分。 别名也可以在功能内使用。 别名必须为const。

例子：

const staticHelper = importedNamespace.staticHelper;
const CONSTANT_NAME = ImportedClass.CONSTANT_NAME;
const {assert, assertInstanceof} = asserts;

6.2.6 非常量域名称

非恒定字段名称（静态或其他）用lowerCamelCase编写，私有字段后跟下划线。

这些名称通常是名词或名词短语。 例如，calculatedValues或index_。

6.2.7 参数名称

参数名称写在lowerCamelCase中。 请注意，即使参数需要构造函数，这也适用。

单字符参数名称不应在公共方法中使用。

例外：当第三方框架要求时，参数名称可以以$开头。 此例外不适用于任何其他标识符（例如，局部变量或属性）。

6.2.8 局部变量名称

如上所述，局部变量名称用lowerCamelCase编写，除了模块局部（顶级）常量外。 函数作用域中的常量仍在lowerCamelCase中命名。 请注意，即使变量包含构造函数，也会使用lowerCamelCase。

6.2.9 模板参数名称

模板参数名称应该是简洁的，单个单词或单个字母的标识符，并且必须是大写字母，例如TYPE或THIS。

6.2.10 模块局部名称

未导出的模块本地名称是隐式私有的。 它们未标记为@private，并且不以下划线结尾。 这适用于类，函数，变量，常量，枚举和其他模块本地标识符。

6.3 驼峰案例：定义

有时，有多种合理的方法可以将英语短语转换为驼峰式大小写，例如，当出现首字母缩写词或者类似IPv6或者IOS的异常结构时，为了提高可预测性，Google样式指定了以下（几乎）确定性的方案。

从名字的散文形式开始：

1. 将短语转换为纯ASCII并删除所有撇号。 例如，Müller的算法可能会变成Muellers算法。
2. 将此结果划分为单词，在空格和所有剩余的标点符号（通常为连字符）上分割。
   a. 推荐：如果某个字词在常规用法中已经具有常规的驼峰式外观，请将其拆分为各个组成部分（例如，AdWords变成广告字词）。 请注意，诸如iOS之类的词本身并不是驼峰式的。 它违反任何约定，因此该建议不适用。
3. 现在将所有内容（包括首字母缩写词）都小写，然后仅将第一个字符大写。
   a. …每个单词，以产生大写字母大写字母，或
   b. …除第一个单词外的每个单词，以产生小写的驼峰字母
4. 最后，将所有单词合并为一个标识符。

请注意，几乎完全忽略了原始单词的大小写。

例子：

散文形式	正确形式	错误形式
“XML HTTP request”	XmlHttpRequest	XMLHTTPRequest
“new customer ID”	newCustomerId	newCustomerID
“inner stopwatch”	innerStopwatch	innerStopWatch
“supports IPv6 on iOS?”	supportsIpv6OnIos	supportsIPv6OnIOS
“YouTube importer”	YouTubeImporter	YoutubeImporter*

*表示可接受，但是不推荐。

注意：有些单词在英语中含糊不清的连字符：例如nonempty和non-empty都是正确的，因此方法名checkNonempty和checkNonEmpty同样都是正确的。