ts-google

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Google TypeScript Best Practices

Google TypeScript最佳实践

Comprehensive TypeScript style guide based on Google's internal standards, designed for AI agents and LLMs. Contains 45 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.

基于Google内部标准的全面TypeScript风格指南，专为AI Agent和大语言模型设计。包含8个类别共45条规则，按影响程度排序，可指导自动化重构与代码生成。

When to Apply

适用场景

Reference these guidelines when:

Writing new TypeScript code
Organizing modules and imports
Designing type annotations and interfaces
Creating classes and functions
Reviewing code for style consistency
Refactoring existing TypeScript code

在以下场景中参考本指南：

编写新的TypeScript代码
组织模块与导入
设计类型注解与接口
创建类与函数
评审代码以保证风格一致性
重构现有TypeScript代码

Rule Categories by Priority

按优先级划分的规则类别


module-
types-
class-
func-
control-
error-
naming-
literal-

Priority	Category	Impact	Prefix
1	Module Organization	CRITICAL	`module-`
2	Type Safety	CRITICAL	`types-`
3	Class Design	HIGH	`class-`
4	Function Patterns	HIGH	`func-`
5	Control Flow	MEDIUM-HIGH	`control-`
6	Error Handling	MEDIUM	`error-`
7	Naming & Style	MEDIUM	`naming-`
8	Literals & Coercion	LOW-MEDIUM	`literal-`


module-
types-
class-
func-
control-
error-
naming-
literal-

优先级	类别	影响程度	前缀
1	模块组织	关键	`module-`
2	类型安全	关键	`types-`
3	类设计	高	`class-`
4	函数模式	高	`func-`
5	控制流	中高	`control-`
6	错误处理	中	`error-`
7	命名与风格	中	`naming-`
8	字面量与类型转换	中低	`literal-`

Quick Reference

快速参考

1. Module Organization (CRITICAL)

1. 模块组织（关键）

```
module-named-exports
```
- Use named exports over default exports
```
module-no-mutable-exports
```
- Avoid mutable exports
```
module-es6-modules
```
- Use ES6 modules exclusively
```
module-no-namespaces
```
- Avoid TypeScript namespaces
```
module-import-paths
```
- Use relative paths for project imports
```
module-import-type
```
- Use import type for type-only imports
```
module-export-api-surface
```
- Minimize exported API surface

```
module-named-exports
```
- 优先使用具名导出而非默认导出
```
module-no-mutable-exports
```
- 避免可变导出
```
module-es6-modules
```
- 仅使用ES6 modules
```
module-no-namespaces
```
- 避免使用TypeScript命名空间
```
module-import-paths
```
- 项目内部导入使用相对路径
```
module-import-type
```
- 仅类型导入使用import type
```
module-export-api-surface
```
- 最小化导出的API范围

2. Type Safety (CRITICAL)

2. 类型安全（关键）

```
types-no-any
```
- Never use the any type
```
types-prefer-interfaces
```
- Prefer interfaces over type aliases for objects
```
types-explicit-structural
```
- Explicitly annotate structural types
```
types-nullable-patterns
```
- Handle nullable types correctly
```
types-array-syntax
```
- Use consistent array type syntax
```
types-no-wrapper-types
```
- Never use wrapper object types
```
types-prefer-map-set
```
- Prefer Map and Set over index signatures
```
types-no-empty-object
```
- Avoid empty object type

```
types-no-any
```
- 绝不使用any类型
```
types-prefer-interfaces
```
- 定义对象类型时优先使用interface而非类型别名
```
types-explicit-structural
```
- 显式注解结构类型
```
types-nullable-patterns
```
- 正确处理可空类型
```
types-array-syntax
```
- 使用一致的数组类型语法
```
types-no-wrapper-types
```
- 绝不使用包装对象类型
```
types-prefer-map-set
```
- 优先使用Map和Set而非索引签名
```
types-no-empty-object
```
- 避免使用空对象类型

3. Class Design (HIGH)

3. 类设计（高）

```
class-parameter-properties
```
- Use parameter properties for constructor assignment
```
class-readonly-properties
```
- Mark properties readonly when never reassigned
```
class-no-private-fields
```
- Use TypeScript private over private fields
```
class-no-static-containers
```
- Avoid container classes with only static members
```
class-constructor-parens
```
- Always use parentheses in constructor calls
```
class-no-prototype-manipulation
```
- Never manipulate prototypes directly

```
class-parameter-properties
```
- 使用参数属性简化构造函数赋值
```
class-readonly-properties
```
- 永不重新赋值的属性标记为readonly
```
class-no-private-fields
```
- 使用TypeScript的private修饰符而非私有字段
```
class-no-static-containers
```
- 避免仅包含静态成员的容器类
```
class-constructor-parens
```
- 构造函数调用始终使用括号
```
class-no-prototype-manipulation
```
- 绝不直接操作原型

4. Function Patterns (HIGH)

4. 函数模式（高）

```
func-declarations-over-expressions
```
- Prefer function declarations over expressions
```
func-arrow-concise-bodies
```
- Use concise arrow function bodies appropriately
```
func-avoid-this-rebinding
```
- Avoid rebinding this
```
func-rest-parameters
```
- Use rest parameters over arguments
```
func-generator-syntax
```
- Use correct generator function syntax
```
func-default-parameters
```
- Use default parameters sparingly

```
func-declarations-over-expressions
```
- 优先使用函数声明而非函数表达式
```
func-arrow-concise-bodies
```
- 合理使用箭头函数的简洁体语法
```
func-avoid-this-rebinding
```
- 避免重新绑定this
```
func-rest-parameters
```
- 使用剩余参数而非arguments对象
```
func-generator-syntax
```
- 使用正确的生成器函数语法
```
func-default-parameters
```
- 谨慎使用默认参数

5. Control Flow (MEDIUM-HIGH)

5. 控制流（中高）

```
control-always-use-braces
```
- Always use braces for control structures
```
control-triple-equals
```
- Always use triple equals
```
control-for-of-iteration
```
- Prefer for-of over for-in for arrays
```
control-switch-default
```
- Always include default case in switch
```
control-no-assignment-in-condition
```
- Avoid assignment in conditional expressions

```
control-always-use-braces
```
- 控制结构始终使用大括号
```
control-triple-equals
```
- 始终使用三等号进行比较
```
control-for-of-iteration
```
- 遍历数组时优先使用for-of而非for-in
```
control-switch-default
```
- switch语句始终包含default分支
```
control-no-assignment-in-condition
```
- 避免在条件表达式中进行赋值操作

6. Error Handling (MEDIUM)

6. 错误处理（中）

```
error-throw-errors
```
- Always throw Error instances
```
error-catch-unknown
```
- Type catch clause variables as unknown
```
error-empty-catch-comments
```
- Document empty catch blocks
```
error-avoid-assertions
```
- Avoid type and non-null assertions

```
error-throw-errors
```
- 始终抛出Error实例
```
error-catch-unknown
```
- catch子句的变量类型标记为unknown
```
error-empty-catch-comments
```
- 为空的catch块添加注释说明
```
error-avoid-assertions
```
- 避免使用类型断言和非空断言

7. Naming & Style (MEDIUM)

7. 命名与风格（中）

```
naming-identifier-styles
```
- Use correct identifier naming styles
```
naming-descriptive-names
```
- Use descriptive names
```
naming-no-decorative-underscores
```
- Avoid decorative underscores
```
naming-no-interface-prefix
```
- No I prefix for interfaces
```
naming-constants
```
- Use CONSTANT_CASE for true constants

```
naming-identifier-styles
```
- 使用正确的标识符命名风格
```
naming-descriptive-names
```
- 使用具有描述性的名称
```
naming-no-decorative-underscores
```
- 避免使用装饰性下划线
```
naming-no-interface-prefix
```
- 接口名称不使用I前缀
```
naming-constants
```
- 真正的常量使用CONSTANT_CASE命名

8. Literals & Coercion (LOW-MEDIUM)

8. 字面量与类型转换（中低）

```
literal-single-quotes
```
- Use single quotes for strings
```
literal-number-formats
```
- Use correct number literal formats
```
literal-explicit-coercion
```
- Use explicit type coercion
```
literal-array-constructor
```
- Avoid Array constructor

```
literal-single-quotes
```
- 字符串使用单引号
```
literal-number-formats
```
- 使用正确的数字字面量格式
```
literal-explicit-coercion
```
- 使用显式类型转换
```
literal-array-constructor
```
- 避免使用Array构造函数

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

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

章节定义 - 类别结构与影响程度说明
规则模板 - 添加新规则的模板

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	版本与参考信息