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

Google的Javascript风格指南

    • 6 命名规范
      • 6.1 所有标识符的通用规则
      • 6.2 标识符类型规则
        • 6.2.1 Package命名
        • 6.2.2 Class命名
        • 6.2.3 Method命名
        • 6.2.4 Enum命名
        • 6.2.5 Constant命名
          • 6.2.5.1 “constant”的定义
          • 6.2.5.2 本地别名
        • 6.2.6 非常量域名称
        • 6.2.7 参数名称
        • 6.2.8 局部变量名称
        • 6.2.9 模板参数名称
        • 6.2.10 模块局部名称
      • 6.3 驼峰案例:定义

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 __,例如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 */ mutableCollection = new Set();
const /** ImmutableSet */ 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同样都是正确的。

你可能感兴趣的:(程序设计语言,javascript,前端)