文件名

文件名须全部小写,下划线(_)和短横线(-)

源文件采用 UTF-8 编码。

非空代码块:K&R 风格

  • 左花括号不另起新行

  • 左花括号后紧跟换行

  • 右花括号前需要换行

  • 如果右花括号结束了语句,或者它是函数、类、类中的方法的结束括号,则其后面需要换行。如果后面紧跟的是 elsecatchwhile,或逗号,分号以及右括号,则不需要跟一个换行。

代码块中的编进:+2 个空格

新开代码块中代码需要加 2 个空格的缩进

数组字面量:类代码块(block-like)
const c = [0, 1, 2];

someMethod(foo, [
0, 1, 2,
], bar);
Switch 语句

一如其他代码块一样,switch 语句中每个条件块也是增加 2 个空格的缩进。 每个 switch 标签后新起一行,加缩进,就像是创建了一个带花括号的代码块一样。每个标签开始时缩进又恢复,相当于只有 switch 标签中的内容是当作代码块来处理的。

break 关键字后面的空行是可选的。

switch (animal) {
case Animal.BANDERSNATCH:
handleBandersnatch();
break; case Animal.JABBERWOCK:
handleJabberwock();
break; default:
throw new Error('Unknown animal');
}

声明语句

一个声明占一行

每个声明语句后都跟换行。

分号是必需的

语句后需用分号结束。不能依赖于编辑器的自动分号插入功能。

最大列宽:80

何处该换行

换行的的准则是:尽量在优先级高的语法层面(higher syntactic level)进行

currentEstimate =
calc(currentEstimate + x * currentEstimate) /
2.0f;

语法优先级从高到低依次为:赋值,除法,函数调用,参数,数字常量。

换行后后续行至少有 4 个空格的缩进

当发生换行时,第一行后面跟着的其他行至少缩进 4 个空格,除非满足代码块的缩进规则,另说。

换行后后续跟随多行时,缩进可适当大于 4 个空格。通常,语法中低优先级的后续行以 4 的倍数进行缩进,如果只有两行并且处于同一优先级,则保持一样的缩进即可。

空格

垂直方向的空格

以下场景需要有一个空行:

  1. 类或对象中的方法间 a. 例外的情形:对象中属性间的空行是可选的。如果有的话,一般是用来将属性进行分组。

  2. 方法体中,尽量少地使用空行来进行代码的分隔。函数体开始和结束都不要加空行。 3.类或对象中首个方法前及最后一个方法后的空行,既不提倡也不反对。

  3. 适用此风格中其他条目的规定(e.g.3.4 goog.require statements)。

连续多个空行不是必需的,但了不鼓励这么做。

水平方向的空格

水平方向的空格依位置为定,有三种大的分类:行首(一行的开始),行尾(一行的结束)以及行间(一行中除去行首及行尾的部分)。行首的空格(i.e. 缩进)无处不在。行尾的空格是禁止的。

除了 Javascript 本身及其他规则的要求,还有字面量,注释,JSDoc 等需要的空格外,单个的 ASCII 类型的空格在以下情形中也是需要的。

  1. 将关键字(譬如 ifforcatch)与括号(()分隔。

  2. 将关键字(elsecatch)与闭合括号(}) 分隔。

  3. 对于左花括号有两种例外: a. 作为函数首个参数的对象之前,数组中首个对象元素 (e.g. foo({a: [{c: d}]})) b. 在模板表达式中,因为模板语法的限制不能加空格(e.g. abc${1 + 2}def)。

  4. 二元,三元操作符的两边

  5. 逗号或分号后。但其前面是不允许有空格的。

  6. 对象字面量中冒号后面。

  7. 双斜线(//)两边。这里可以使用多个空格,但也不是必需的。

  8. JSDoc 注释及其两边 e.g. 简写的类型声明 this.foo = /** @type {number} */ (bar); 或类型转换(cast)function(/** string */ foo) {

函数参数

推荐将函数的所有参数放在与函数名同一行的位置。如果这样会导致列宽超限,那参数应该以一种易读的方式进行换行。为了节省空间,尽量超过宽度限制时才进行换行,换行后每个参数一行以提高可读性。换行后缩进为 4 个空格。与括号对齐是可以的,但不推荐。以下是觉的参数换行示例:

// Arguments start on a new line, indented four spaces. Preferred when the
// arguments don't fit on the same line with the function name (or the keyword
// "function") but fit entirely on the second line. Works with very long
// function names, survives renaming without reindenting, low on space.
doSomething(
descriptiveArgumentOne, descriptiveArgumentTwo, descriptiveArgumentThree) {
// …
} // If the argument list is longer, wrap at 80. Uses less vertical space,
// but violates the rectangle rule and is thus not recommended.
doSomething(veryDescriptiveArgumentNumberOne, veryDescriptiveArgumentTwo,
tableModelEventHandlerProxy, artichokeDescriptorAdapterIterator) {
// …
} // Four-space, one argument per line. Works with long function names,
// survives renaming, and emphasizes each argument.
doSomething(
veryDescriptiveArgumentNumberOne,
veryDescriptiveArgumentTwo,
tableModelEventHandlerProxy,
artichokeDescriptorAdapterIterator) {
// …
}

注释

块状注释

块状注释与被注释代码保持相同缩进。/* ... */// 都是。对于多行的 /* ... */ 注释,后续注释行以 * 开头且与上一行缩进保持一致。参数的注释紧随参数之后,用于在函数名或参数名无法完全表达其意思的情况。

注意区分 JSDoc(/** ... */),上面不注释不能写成这样。

本地变量的声明

使用 constlet

所有本地变量使用 constlet 来声明。默认使用 const,除非该变量需要重新赋值。杜绝使用 var

一次声明一个变量

一次只声明一个本地变量,let a = 1, b = 2; 这样的做法是禁止的。

需要时才声明,声明后尽快初始化

本地变量不要全部一次性声明在代码块的开头。声明在该变量每一次需要被使用的地方,以减少其影响范围。

尽量标明类型

JSDoc 类型注释可以添加在声明语句上面,或者内联到变量名前面。

const /** !Array<number> */ data = [];

/** @type {!Array<number>} */
const data = [];

数组字面量

尾部加逗号

始终在元素后面带上一个结束的逗号。

属性引号保持一致(字典键的类型一致)

对象属性分为不包含引号或 Symbols 的 structs 类型和包含引号或运算属性的 dicts 类型。两种类型不要混合使用,应该保持一致。

标识符类型的命名规则

包名

包名使用小写开头的驼峰命名 lowerCamelCase

类名

类,接口,record (这是什么?) 以及 typedef names (类型定义符) 使用大写开头的驼峰 UpperCamelCase

未被导出的类只本地使用,并没有用 @private 标识,所以命名上不需要以下划线结尾。

类型名称通常为名词或名词短语。比如,RequestImmutableList,或者 VisibilityMode。此外,接口名有时会是一个形容词或形容短语(比如 Readable)。

方法名

方法名使用小写开头的驼峰。私有方法需以下划线结尾。

方法名一般为动词或动词短语。比如 sendMessage 或者 stop_。属性的 Getter 或 Setter 不是必需的,如果有的话,也是小写驼峰命名且需要类似这样 getFoo(对于布尔值使用 isFoohasFoo 形式),setFoo(value)

注:私有属性或方法以下划线开头才是主流吧

单元测试代码中的方法名会出现用下划线来分隔组件形式。一种典型的形式是这样的test<MethodUnderTest>_<state>,例如 testPop_emptyStack。对于这种测试代码中的方法,命名上没有统一的要求

枚举

枚举使用大写开头的驼峰,和类相似,一般一个单数形式的名词。枚举中的元素写成 CONSTANT_CASE

常量

常量写成 CONSTANT_CASE:所有字母使用大写,以下划线分隔单词。私有静态属性可以用内部变量代替,所以不会有使用私有枚举的情况,也就无需将常量以下划线结尾来命名。

常量的定义

每个常量都是 @const 标识的静态属性或 模块内部通过 const 声明的变量,但并不是所有 @const 标识的静态属性或 const 声明的变量都是常理。需要常量时,先想清楚该对象是否真的不可变。例如,如果该对象中做生意状态可被改变,显然不适合作为常量。只是想着不去改变它的值是不够的,我们要求它需要从本质上来说应该一成不变。

非常量字段

非常量字段(静态或其他)使用小写开头的驼峰,如果是私有的私有的则以下划线结尾。

一般是名词或名词短语。例如 computedValuesindex_

参数

参数使用小写开头的驼峰。即使参数需要一个构造器来初始化时,也是这一规则。

公有方法的参数名不能只使用一个字母。

例外:如果三方库需要,参数名可以用 $ 开头。此例外不适用于其他标识符(e.g. 本地变量或属性)。

本地变量

本地变量使用小写开头的驼峰,除非是上面介绍过的本地常量。函数中的常量命名仍然使用小写开头的驼峰lowerCamelCase。即使该变量指向的是构造器也使用 lowerCamelCase。

模板参数/Template parameter names

模板参数力求简洁,用一个单词,一个字母表示,全部使用大写,例如 TYPETHIS

驼峰:定义

有时将一个英文短语转成驼峰有很多形式,例如首字母进行缩略,IPv6 以及 iOS 这种都有出现。为保证代码可控,本规范规定出如下规则。

  1. 将短语移除撇号转成 ASCII 表示。例如 Müller's algorithm 表示成 Muellers algorithm

  2. 将上述结果拆分成单词,以空格或其他不发音符号(中横线)进行分隔。 a. 推荐的做法:如果其中包含一个已经常用的驼峰翻译,直接提取出来(e.g. AdWords 会成为 ad words)。需要注意的是 iOS 本身并不是个驼峰形式,它不属性任何形式,所以它不适用本条规则。

  3. 将所有字母转成小写,然后将以下情况中的首字母大写: a. 每个单词的首字母,这样便得到了大写开头的驼峰 b. 除首个单词的其他所有单词的首字母,这样得到小写开头的驼峰

  4. 将上述结果合并。

过程中原来名称中的大小写均被忽略。

示例:

Prose form Correct Incorrect
XML HTTP request XmlHttpRequest XMLHTTPRequest
new customer ID newCustomerId newCustomerID
inner stopwatch innerStopwatch innerStopWatch
supports IPv6 on iOS? supportsIpv6OnIos supportsIPv6OnIOS
ouTube importer YouTubeImporter YoutubeImporter*

*这种情况可接受,但不推荐。

注释:一些英文词汇通过中横线连接的方式是有歧义的,比如 "nonempty" 和 "non-empty" 都是正确写法,所以方法名 checkNonempty checkNonEmpty 都算正确。

JSDoc

JSDoc 使用在了所有的类,字段以及方法上。

通用形式

JSDoc 基本的形式如下:

/**
* Multiple lines of JSDoc text are written here,
* wrapped normally.
* @param {number} arg A number to do something to.
*/
function doSomething(arg) { … }

或者这种单行的形式:

/** @const @private {!Foo} A short bit of JSDoc. */
this.foo_ = foo;

如果单行形式长到需要折行,则需要切换到多行模式而不是使用单行形式。

有许多工具会对 JSDoc 文档进行解析以提取出有效的信息对代码进行检查和优化。所以这些注释需要好好写。

Markdown

JSDoc 支持 Markdown,所以必要时可包含 HTML。

工具会自动提取 JSDoc 的内容,其中自己书写的格式会被忽略。比如如果你写成下面这个样子:

/**
* Computes weight based on three factors:
* items sent
* items received
* last timestamp
*/

最终提取出来是这样的:

Computes weight based on three factors: items sent items received last timestamp

取而代之,我们应该按 markdown 的语法来格式化:

 

JSDoc tags

本规则可使用 JSDoc tags 的一个子集。详细列表见 9.1 JSDoc tag reference。大部分 tags 独占一行。

错误的示例:

/**
* The "param" tag must occupy its own line and may not be combined.
* @param {number} left @param {number} right
*/
function add(left, right) { ... }

简单的 tag 无需额外数据(比如 @private@const@final@export),可以合并到一行。

 
/**
* Place more complex annotations (like "implements" and "template")
* on their own lines. Multiple simple tags (like "export" and "final")
* may be combined in one line.
* @export @final
* @implements {Iterable<TYPE>}
* @template TYPE
*/
class MyClass {
/**
* @param {!ObjType} obj Some object.
* @param {number=} num An optional number.
*/
constructor(obj, num = 42) {
/** @private @const {!Array<!ObjType|number>} */
this.data_ = [obj, num];
}
}

关于合并及合并后的顺序没有明确的规范,代码中保持一致即可。

详细的类型信息可参见 Annotating JavaScript for the Closure CompilerTypes in the Closure Type System

换行

换行之后的 tag 块使用四个空格进行缩进。

/**
* Illustrates line wrapping for long param/return descriptions.
* @param {string} foo This is a param with a description too long to fit in
* one line.
* @return {number} This returns something that has a description too long to
* fit in one line.
*/
exports.method = function(foo) {
return 5;
};

@fileoverview 换行时不缩进。

文件头部注释

一个文件可以在头部有个总览。包括版权信息,作者以及默认可选的可见信息/visibility level等。文件中包含多个类时,头部这个总览显得很有必要。它可以帮助别人快速了解该文件的内容。如果写了,则应该有一个描述字段简单介绍文件中的内容以及一些依赖,或者其他信息。换行后不缩进。

示例:

/**
* @fileoverview Description of file, its uses and information
* about its dependencies.
* @package
*/

类的注释

类,接口以及 records 需要有描述,参数,实现的接口以及可见性或其他适当的 tags 注释。类的描述需要告诉读者类的作用及何时使用该类,以及其他一些可以帮助别人正确使用该类的有用信息。构造器上的文本描述可省略。@constructor@extends 不与 class 一起使用,除非该类是用来声明接口 @interface 或者扩展一个泛型类。

/**
* A fancier event target that does cool things.
* @implements {Iterable<string>}
*/
class MyFancyTarget extends EventTarget {
/**
* @param {string} arg1 An argument that makes this more interesting.
* @param {!Array<number>} arg2 List of numbers to be processed.
*/
constructor(arg1, arg2) {
// ...
}
}; /**
* Records are also helpful.
* @extends {Iterator<TYPE>}
* @record
* @template TYPE
*/
class Listable {
/** @return {TYPE} The next item in line to be returned. */
next() {}
}

枚举和 typedef 注释

枚举和 typedef 需要写文档。仅有的枚举和 typedef 其文档的描述不能为空。枚举中单个元素的文档可直接写在元素的前面一行。

/**
* A useful type union, which is reused often.
* @typedef {!Bandersnatch|!BandersnatchType}
*/
let CoolUnionType; /**
* Types of bandersnatches.
* @enum {string}
*/
const BandersnatchType = {
/** This kind is really frumious. */
FRUMIOUS: 'frumious',
/** The less-frumious kind. */
MANXOME: 'manxome',
};

Typedefs 可方便地用于定义 records 类型,或 unions 的别名,复杂函数,或者 泛型类型。Typedefs 不适合用来定义字段很多的 records,因为其不支持对每个字段进行文档书写,也不适合用于模板或递归引用中。对于大型 records 使用 @record

方法与函数

参数和返回类型需要写文档。必要时 this 也需要在文档中说明。方法,参数及返回的描述在方法的其他 JSDoc 中或方法签名中有表述,那么也是可以省略的。方法的描述应使用第三人称。如果方法重载父类中的方法,需要使用 @override 标识。重载方法需要包含所有的参数 @param 以及 @return 如果类型有变的话,如果没变也可省略。

/** This is a class. */
class SomeClass extends SomeBaseClass {
/**
* Operates on an instance of MyClass and returns something.
* @param {!MyClass} obj An object that for some reason needs detailed
* explanation that spans multiple lines.
* @param {!OtherClass} obviousOtherClass
* @return {boolean} Whether something occurred.
*/
someMethod(obj, obviousOtherClass) { ... } /** @override */
overriddenMethod(param) { ... }
} /**
* Demonstrates how top-level functions follow the same rules. This one
* makes an array.
* @param {TYPE} arg
* @return {!Array<TYPE>}
* @template TYPE
*/
function makeArray(arg) { ... }

匿名函数不需要写 JSDoc,但在自动推荐参数类型有困难时,也可手动指定一下类型。

promise.then(
(/** !Array<number|string> */ items) => {
doSomethingWith(items);
return /** @type {string} */ (items[0]);
});

属性

属性的类型需要加文档。对于私有属性如果其命名已经很好地提示了其类型,则描述可省略。

公有的常量与属性是一样的文档写法。当 @const 类型的属性从一个表达式初始化时,是能明显看出其类型的,此时其显式的类型指定可省略。

小贴士:@const 属性的类型从构造器的参数进行初始化时,其类型是“显然”的,因为参数上面声明了类型,或者从一个函数调用进行初始化,因为函数返回值的类型也是声明了的。对于非常量或者它的值来源不是很明朗的情况下才需要指定其类型。

/** My class. */
class MyClass {
/** @param {string=} someString */
constructor(someString = 'default string') {
/** @private @const */
this.someString_ = someString; /** @private @const {!OtherType} */
this.someOtherThing_ = functionThatReturnsAThing(); /**
* Maximum number of things per pane.
* @type {number}
*/
this.someProperty = 4;
}
} /**
* The number of times we'll try before giving up.
* @const
*/
MyClass.RETRY_COUNT = 33;

警告

如何处理警告

解决之前,先明白警告的意思。如果不清楚,可以询问。

一旦了解之后,可进行如下操作:

  1. 首先,修复或找替代方案。 尝试针对该警告进行修复,或者换种方式实现相同的功能同时规避掉警告。

  2. 或者,检查看是否是一个误报。 如果确认代码没问题,警告是误报,写下相应注释并添加 @suppress标识。

  3. 或者,留下 TODO 注释。 这是最次的做法。这种做法相当于直接忽略警告,直到时机成熟再解决。

将警告控制在最小范围

将警告控制在最小合理的作用域范围,通常一个本地变量或很小的方法范围内。然后可以将这个变量或方法单独提取出来。

示例:

/** @suppress {uselessCode} Unrecognized 'use asm' declaration */
function fn() {
'use asm';
return 0;
}

一个类中大量的 @suppress 也好过编译时报大量的警告。

已有代码的重新格式化

更新已有代码时,遵循以下原则:

  1. 没必要更新所有老代码以满足本规范。需要在成本与代码一致性之间找个平衡点。规范不断在演变,花大成本更新老代码需要折衷。然而,如果老文件大部分都被修改了的话,那可以顺便将其全部改为符合现在的规范。

  2. 注意控制改动范围。如果你发现需要投入大量精力去更新代码而影响了当前需求的进展,考虑将这些老代码的更新另起一个分支。

新增代码:遵循本规范

全新创建的文件应该全部遵循本规范,某些包中其他类型文件有其他规范的另说。

向一个不是遵循本规范而写的文件添加新代码时,推荐先重新格式化当前文件

如果重新格式化完不成,那么新加的代码应该与老代码尽量保持一致,但不要滥用规范。

Google代码规范的更多相关文章

  1. Google代码规范工具Cpplint的使用

    Cpplint是一个python脚本,Google使用它作为自己的C++代码规范检查工具. 假设你所在的公司也使用Google C++代码规范,那么你有必要了解下Cpplint. 以下说一下Cppli ...

  2. c/c++编码规范(3)--google代码规范检测工具cpplint.py

    cpplint.py是来自google开源项目风格错误检测工具.它是一个python脚本,和google开源项目风格指南一同发布.下载地址:https://github.com/google/styl ...

  3. 阅读Google的C++代码规范有感

    李开复曾在微博上说过,Google的C++代码规范是全球最好的一份C++代码规范,没有之一.最近花了点时间看了下这份代码规范,收获确实很大,在编程过程中一些乱七八糟的坏习惯也该改一改了.最新的英文版见 ...

  4. [转]Google的C++代码规范

    转自:https://blog.csdn.net/freeking101/article/details/78930381 英文版:http://google-styleguide.googlecod ...

  5. Google的C++代码规范

      英文版:http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml 中文版:http://zh-google-styleguide ...

  6. JavaScript必备:Google发布的JS代码规范(转)

    [翻译]关于Google发布的JS代码规范,你需要了解什么? 翻译 | WhiteYin 译文 | https://github.com/WhiteYin/translation/issues/10 ...

  7. Google 公司的代码规范

    如题: C++ , Objective-C, Java, Python, R, Shell, HTML/CSS, JavaScript, AngularJS, Common Lisp ,Vimscri ...

  8. electron教程(番外篇一): 开发环境及插件, VSCode调试, ESLint + Google JavaScript Style Guide代码规范

    我的electron教程系列 electron教程(一): electron的安装和项目的创建 electron教程(番外篇一): 开发环境及插件, VSCode调试, ESLint + Google ...

  9. Objective-C 代码规范(Code Style)

    我们写出来的代码会给很多人看,为了使代码清晰简洁,方便阅读理解,都会统一遵从一定的代码规范,Objective-C同样如此. 主要参考规范: 1.Google Objective-C Style Gu ...

随机推荐

  1. MySQL 导出数据库,出现 “mysqldump: Got error: 1146”

    出现场景 在 cmd 导出数据库时: mysqldump -hlocalhost -uroot -p student_db > C:\student_db.sql 出现: mysqldump: ...

  2. MySQL 无法启动,出现 “发生系统错误 1067。”

    出现场景 使用 net start mysql 时无法启动,并出现:发生系统错误 1067. 解决过程 很多情况都可以导致该错误提示,可以先查找 "Windows 日志" : 打开 ...

  3. Servlet 学习

    3.1 概念 运行在服务器端的小程序 Servlet 就是一个接口 定义JAVA类被浏览器访问(Tomact 识别)的规则 将来 我们需要自定义一个类 实现servlet 接口 重写方法 3.2 快速 ...

  4. 第七节:语法总结(1)(自动属性、out参数、对象初始化器、var和dynamic等)

    一. 语法糖简介   语法糖也译为糖衣语法,是由英国计算机科学家彼得·约翰·兰达(Peter J. Landin)发明的一个术语,指计算机语言中添加的某种语法,这种语法对语言的功能并没有影响,但是更方 ...

  5. SpringBoot系列: 设计Restful风格的API

    RESTful 架构REST 并非一种技术或规范, 而是一种架构风格, 如果一个架构符合Rest的约束条件和原则, 就可以称作是 RESTful 架构. REST全称是Representational ...

  6. Groovy 设计模式 -- 适配器模式

    Adapter Pattern http://groovy-lang.org/design-patterns.html#_adapter_pattern 适配器模式,对象存在一个接口, 此接口在此对象 ...

  7. PhpStorm+xdebug调试——更新

    之前写过一篇<PhpStorm+xdebug+postman调试>,但是经过后来一段时间的使用,发现有些累赘.这里介绍一种比较简单方便的操作. 在上一篇文章中有一段“ 7.设置Server ...

  8. struts2简单入门-数据校验

    数据校验流程 校验数据的方式 重写execute方法在内部写校验代码 public class LoginAdminAction extends ActionSupport { private Use ...

  9. 第十三章 部署Java应用程序

    打包 清单文件被命名为MANIFEST.MF,用于描述归档特征. 清单文件被分为多个节, 第一节被称为主节,作用于整个文件; 其他节则必须起始于Name的条目. 节之间空行分开. jar cfm JA ...

  10. pythonのsimple_tag

    当我们需要在页面种直接调用py文件中的某些方法时,我们就要用到simple_tag.具体步骤如下: 1.在某个app下创建templatetags文件夹,切记该名称是不可以改变的. 2.在该文件夹下创 ...