js-google

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Google JavaScript Best Practices

Google JavaScript 最佳实践

Comprehensive JavaScript style and best practices guide based on Google's official JavaScript Style Guide, designed for AI agents and LLMs. Contains 47 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.

基于Google官方JavaScript风格指南的全面JavaScript风格与最佳实践指南，专为AI Agent和LLM设计。包含8个类别下的47条规则，按影响优先级排序，以指导自动化重构和代码生成。

When to Apply

适用场景

Reference these guidelines when:

Writing new JavaScript or ES6+ code
Structuring modules and managing imports/exports
Adding JSDoc type annotations and documentation
Reviewing code for naming and style consistency
Refactoring existing JavaScript code

在以下场景参考本指南：

编写新的JavaScript或ES6+代码
构建模块结构并管理导入/导出
添加JSDoc类型注解与文档
评审代码的命名与风格一致性
重构现有JavaScript代码

Rule Categories by Priority

按优先级划分的规则类别


module-
lang-
type-
naming-
control-
func-
data-
format-

Priority	Category	Impact	Prefix
1	Module System & Imports	CRITICAL	`module-`
2	Language Features	CRITICAL	`lang-`
3	Type Safety & JSDoc	HIGH	`type-`
4	Naming Conventions	HIGH	`naming-`
5	Control Flow & Error Handling	MEDIUM-HIGH	`control-`
6	Functions & Parameters	MEDIUM	`func-`
7	Objects & Arrays	MEDIUM	`data-`
8	Formatting & Style	LOW	`format-`


module-
lang-
type-
naming-
control-
func-
data-
format-

优先级	类别	影响程度	前缀
1	模块系统与导入	关键	`module-`
2	语言特性	关键	`lang-`
3	类型安全与JSDoc	高	`type-`
4	命名规范	高	`naming-`
5	控制流与错误处理	中高	`control-`
6	函数与参数	中	`func-`
7	对象与数组	中	`data-`
8	格式与风格	低	`format-`

Quick Reference

快速参考

1. Module System & Imports (CRITICAL)

1. 模块系统与导入（关键）

```
module-avoid-circular-dependencies
```
- Prevent loading failures from circular imports
```
module-file-extension-in-imports
```
- Include .js extension in import paths
```
module-named-exports-over-default
```
- Prefer named exports for consistency
```
module-no-duplicate-imports
```
- Import from same file only once
```
module-no-import-aliasing
```
- Keep original export names
```
module-source-file-structure
```
- Follow standard file structure order

```
module-avoid-circular-dependencies
```
- 避免循环导入导致的加载失败
```
module-file-extension-in-imports
```
- 在导入路径中包含.js扩展名
```
module-named-exports-over-default
```
- 优先使用命名导出以保持一致性
```
module-no-duplicate-imports
```
- 同一文件仅导入一次
```
module-no-import-aliasing
```
- 保留原始导出名称
```
module-source-file-structure
```
- 遵循标准文件结构顺序

2. Language Features (CRITICAL)

2. 语言特性（关键）

```
lang-const-over-let-over-var
```
- Use const by default, never var
```
lang-es6-classes-over-prototypes
```
- Use class syntax over prototype manipulation
```
lang-explicit-semicolons
```
- Always use explicit semicolons
```
lang-no-eval
```
- Never use eval or Function constructor
```
lang-no-modify-builtins
```
- Never modify built-in prototypes
```
lang-no-non-standard-features
```
- Use only standard ECMAScript features
```
lang-no-primitive-wrappers
```
- Never use primitive wrapper objects
```
lang-no-with-statement
```
- Never use the with statement

```
lang-const-over-let-over-var
```
- 默认使用const，绝不使用var
```
lang-es6-classes-over-prototypes
```
- 使用类语法而非原型操作
```
lang-explicit-semicolons
```
- 始终使用显式分号
```
lang-no-eval
```
- 绝不使用eval或Function构造函数
```
lang-no-modify-builtins
```
- 绝不修改内置原型
```
lang-no-non-standard-features
```
- 仅使用标准ECMAScript特性
```
lang-no-primitive-wrappers
```
- 绝不使用原始值包装对象
```
lang-no-with-statement
```
- 绝不使用with语句

3. Type Safety & JSDoc (HIGH)

3. 类型安全与JSDoc（高）

```
type-cast-with-parentheses
```
- Use parentheses for type casts
```
type-enum-annotations
```
- Annotate enums with static literal values
```
type-explicit-nullability
```
- Use explicit nullability modifiers
```
type-jsdoc-required-for-exports
```
- Require JSDoc for exported functions
```
type-template-parameters
```
- Always specify template parameters
```
type-typedef-for-complex-types
```
- Use typedef for complex object types

```
type-cast-with-parentheses
```
- 使用括号进行类型转换
```
type-enum-annotations
```
- 为枚举添加静态字面量值注解
```
type-explicit-nullability
```
- 使用显式可空性修饰符
```
type-jsdoc-required-for-exports
```
- 导出函数必须添加JSDoc
```
type-template-parameters
```
- 始终指定模板参数
```
type-typedef-for-complex-types
```
- 为复杂对象类型使用typedef

4. Naming Conventions (HIGH)

4. 命名规范（高）

```
naming-constant-case-for-constants
```
- Use CONSTANT_CASE for immutable values
```
naming-descriptive-over-brief
```
- Prefer descriptive names over brevity
```
naming-file-naming-conventions
```
- Use lowercase with dashes or underscores
```
naming-lowercamelcase-for-methods
```
- Use lowerCamelCase for methods and variables
```
naming-no-dollar-prefix
```
- Avoid dollar sign prefix in identifiers
```
naming-uppercamelcase-for-classes
```
- Use UpperCamelCase for classes

```
naming-constant-case-for-constants
```
- 不可变值使用CONSTANT_CASE命名
```
naming-descriptive-over-brief
```
- 优先使用描述性名称而非简短名称
```
naming-file-naming-conventions
```
- 使用小写加短横线或下划线命名文件
```
naming-lowercamelcase-for-methods
```
- 方法与变量使用lowerCamelCase命名
```
naming-no-dollar-prefix
```
- 标识符避免使用美元符号前缀
```
naming-uppercamelcase-for-classes
```
- 类使用UpperCamelCase命名

5. Control Flow & Error Handling (MEDIUM-HIGH)

5. 控制流与错误处理（中高）

```
control-comment-empty-catch
```
- Document empty catch blocks
```
control-for-of-over-for-in
```
- Prefer for-of over for-in
```
control-strict-equality
```
- Use strict equality except for null checks
```
control-switch-default-last
```
- Always include default case in switch
```
control-throw-error-objects
```
- Always throw Error objects

```
control-comment-empty-catch
```
- 为空catch块添加文档说明
```
control-for-of-over-for-in
```
- 优先使用for-of而非for-in
```
control-strict-equality
```
- 除空值检查外，使用严格相等运算符
```
control-switch-default-last
```
- switch语句中始终包含default分支
```
control-throw-error-objects
```
- 始终抛出Error对象

6. Functions & Parameters (MEDIUM)

6. 函数与参数（中）

```
func-arrow-functions-for-nested
```
- Prefer arrow functions for nested functions
```
func-arrow-parentheses
```
- Always use parentheses around arrow params
```
func-default-parameters
```
- Use default parameters instead of conditionals
```
func-rest-parameters-over-arguments
```
- Use rest parameters over arguments
```
func-spread-over-apply
```
- Use spread operator instead of apply

```
func-arrow-functions-for-nested
```
- 嵌套函数优先使用箭头函数
```
func-arrow-parentheses
```
- 箭头函数参数始终使用括号包裹
```
func-default-parameters
```
- 使用默认参数而非条件判断
```
func-rest-parameters-over-arguments
```
- 使用剩余参数而非arguments对象
```
func-spread-over-apply
```
- 使用扩展运算符而非apply方法

7. Objects & Arrays (MEDIUM)

7. 对象与数组（中）

```
data-array-literals-over-constructor
```
- Use array literals over Array constructor
```
data-destructuring-for-multiple-values
```
- Use destructuring for multiple properties
```
data-no-mixing-quoted-unquoted-keys
```
- Never mix quoted and unquoted keys
```
data-object-literals-over-constructor
```
- Use object literals over constructor
```
data-spread-over-concat-slice
```
- Use spread over concat and slice
```
data-trailing-commas
```
- Use trailing commas in multi-line literals

```
data-array-literals-over-constructor
```
- 优先使用数组字面量而非Array构造函数
```
data-destructuring-for-multiple-values
```
- 多属性取值使用解构赋值
```
data-no-mixing-quoted-unquoted-keys
```
- 绝不混合使用带引号与不带引号的对象键名
```
data-object-literals-over-constructor
```
- 优先使用对象字面量而非构造函数
```
data-spread-over-concat-slice
```
- 使用扩展运算符而非concat和slice方法
```
data-trailing-commas
```
- 多行字面量中使用 trailing commas

8. Formatting & Style (LOW)

8. 格式与风格（低）

```
format-braces-required
```
- Always use braces for control structures
```
format-column-limit
```
- Limit lines to 80 characters
```
format-one-statement-per-line
```
- Place one statement per line
```
format-single-quotes
```
- Use single quotes for string literals
```
format-two-space-indent
```
- Use two-space indentation

```
format-braces-required
```
- 控制结构始终使用大括号
```
format-column-limit
```
- 每行代码限制为80个字符
```
format-one-statement-per-line
```
- 每行仅包含一条语句
```
format-single-quotes
```
- 字符串字面量使用单引号
```
format-two-space-indent
```
- 使用两个空格缩进

How to Use

使用方法

Read individual reference files for detailed explanations and code examples:

Section definitions - Category structure and impact levels
Rule template - Template for adding new rules

阅读单个参考文件获取详细说明与代码示例：

Section definitions - 类别结构与影响程度说明
Rule template - 添加新规则的模板

Full Compiled Document

完整编译文档

For a complete compiled guide with all rules, see AGENTS.md.

如需包含所有规则的完整指南，请查看AGENTS.md。

Reference Files

参考文件

File	Description
AGENTS.md	Complete compiled guide with all rules
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for new rules
metadata.json	Version and reference information

文件	描述
AGENTS.md	包含所有规则的完整编译指南
references/_sections.md	类别定义与排序
assets/templates/_template.md	新规则模板
metadata.json	版本与参考信息