Back to Details

kotlin-development

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Kotlin Development Best Practices

Kotlin开发最佳实践

General Principles

通用原则

Use English for all code and documentation
Always declare the type of each variable and function
Avoid the
```
any
```
type; create necessary types instead
No blank lines within function bodies

所有代码和文档使用英文
始终声明每个变量和函数的类型
避免使用
```
any
```
类型；必要时创建自定义类型
函数体内部不要留空行

Naming Conventions

命名规范

Case Standards

大小写标准

PascalCase: Classes, interfaces, enums
camelCase: Variables, functions, methods, parameters
UPPERCASE: Environment variables, constants
underscores_case: Files and directories

PascalCase：类、接口、枚举
camelCase：变量、函数、方法、参数
UPPERCASE：环境变量、常量
underscores_case：文件与目录

Naming Guidelines

命名指南

Start each function with a verb (get, set, create, update, delete, etc.)
Use complete words over abbreviations
- Allowed abbreviations: API, URL, i/j for loops, err, ctx, req/res/next
Avoid magic numbers; define constants instead
Boolean variables use prefixes:
```
isLoading
```
,
```
hasError
```
,
```
canDelete
```

函数名称以动词开头（get、set、create、update、delete等）
优先使用完整单词而非缩写
- 允许使用的缩写：API、URL、循环中的i/j、err、ctx、req/res/next
避免使用魔法数字；改用定义常量的方式
布尔变量使用前缀：
```
isLoading
```
、
```
hasError
```
、
```
canDelete
```

Function Design

函数设计

Size and Responsibility

大小与职责

Keep functions under 20 instructions
Each function should have a single responsibility
Extract logic into utility functions when complexity increases

函数代码行数控制在20行以内
每个函数应单一职责
复杂度提升时，将逻辑提取到工具函数中

Naming Functions

函数命名

Use verb-based naming that describes the action
Prefix boolean-returning functions with
```
is
```
,
```
has
```
, or
```
can
```
Prefix void functions with action verbs like
```
execute
```
,
```
save
```
,
```
send
```

使用基于动词的命名，清晰描述动作
返回布尔值的函数以
```
is
```
、
```
has
```
或
```
can
```
为前缀
无返回值（void）的函数以动作动词为前缀，如
```
execute
```
、
```
save
```
、
```
send
```

Reducing Nesting

减少嵌套

Use early returns to handle edge cases first
Extract nested logic into separate functions
Employ higher-order functions (map, filter, reduce) to minimize loops
Prefer arrow functions for simple operations; use named functions otherwise

优先使用提前返回，先处理边缘情况
将嵌套逻辑提取到独立函数中
使用高阶函数（map、filter、reduce）减少循环
简单操作优先使用箭头函数；复杂场景使用命名函数

Parameters

参数处理

Use default parameters instead of null checks
When functions have multiple parameters, consolidate them into objects (RO-RO pattern)
Keep parameter lists short (max 3-4 parameters)

使用默认参数替代空值检查
当函数存在多个参数时，将其整合为对象（RO-RO模式）
保持参数列表简短（最多3-4个参数）

Data Handling

数据处理

Data Classes

数据类

Use data classes for data structures
Encapsulate primitive types in composite types when they represent domain concepts
Validate data internally within data classes

使用数据类定义数据结构
当基本类型代表领域概念时，将其封装为复合类型
在数据类内部进行数据验证

Immutability

不可变性

Prefer immutability for data
Use
```
val
```
for variables that don't change
Use immutable collections when possible
Create new instances instead of mutating existing ones

优先使用不可变数据
对于不会变更的变量使用
```
val
```
尽可能使用不可变集合
创建新实例而非修改现有实例

Classes and Objects

类与对象

Size Guidelines

大小规范

Keep classes under 200 instructions
Limit to fewer than 10 public methods
Limit to fewer than 10 properties

类的代码行数控制在200行以内
公开方法数量不超过10个
属性数量不超过10个

Design Principles

设计原则

Follow SOLID principles
Favor composition over inheritance
Use interfaces for abstraction
Keep classes focused on a single responsibility

遵循SOLID原则
优先使用组合而非继承
使用接口实现抽象
保持类的单一职责

Exception Handling

异常处理

When to Use Exceptions

异常使用场景

Reserve exceptions for truly unexpected errors
Don't use exceptions for control flow
Catch exceptions only to:
- Fix an anticipated issue
- Add context before re-throwing

仅在真正出现意外错误时使用异常
不要将异常用于流程控制
仅在以下情况捕获异常：
- 修复可预见的问题
- 添加上下文信息后重新抛出

Best Practices

最佳实践

Create custom exception types for domain-specific errors
Include meaningful error messages
Log exceptions at appropriate levels

为领域特定错误创建自定义异常类型
包含有意义的错误信息
在适当的日志级别记录异常

Testing

测试

Unit Tests

单元测试

Follow Arrange-Act-Assert convention
Write unit tests for all public functions
Use test doubles (mocks, stubs, fakes) for dependencies
Name tests descriptively to document behavior

遵循Arrange-Act-Assert（准备-执行-断言）规范
为所有公开函数编写单元测试
使用测试替身（mocks、stubs、fakes）处理依赖
测试名称应具有描述性，以说明预期行为

Acceptance Tests

验收测试

Follow Given-When-Then convention
Test user-facing behavior and scenarios
Keep tests independent and repeatable

遵循Given-When-Then（给定-当-则）规范
测试用户可见的行为与场景
保持测试独立且可重复执行

Code Organization

代码组织

Group related functionality together
Keep files focused and cohesive
Use packages/modules to organize code by feature or layer
Maintain consistent file structure across the project

相关功能放在一起
保持文件的专注性与内聚性
使用包/模块按功能或层级组织代码
保持项目文件结构一致