Coding Style Conventions (代码规范)
Instructions
-
确认需求属于本技能范围（命名、格式、检核）
-
先填写 Required Inputs（规则范围、模块、门槛）并冻结
-
依照下方章节顺序套用
-
一次只调整一类规范，避免混杂变更
-
完成后对照 Quick Checklist
When to Use
-
Scenario A：新项目创建规范
-
Scenario C：旧项目现代化基准
Example Prompts
-
"请参考本技能的 Naming Conventions，检查这段 Kotlin 代码命名是否一致"
-
"依照 Detekt 与 Ktlint 配置章节，帮我创建项目规范"
-
"请用 Quick Checklist 审视这个 PR 的风格问题"
Workflow
-
先确认 Required Inputs（适用模块、规则级别、阻挡条件）
-
对照 Naming Conventions 设置命名规则
-
依 Detekt / Ktlint 配置落实到项目
-
执行 Style Gate，再用 Quick Checklist 验收
Practical Notes (2026)
-
CI Gate 仅针对变更文件运行 Lint/Detekt/Ktlint
-
规范调整与功能变更分开提交，方便回溯
-
Code Review 以 Checklist 作为硬性验收
-
禁止在功能 PR 临时放宽规则，规则变更需独立 PR
-
Baseline 只减不增，新增违规必须当次修复
Minimal Template
目标: 适用范围: 阻挡门槛: Baseline 策略: 规范重点: 检核方式: 验收: Quick Checklist
Required Inputs (执行前输入)
-
适用范围 （全仓 / 模块 / feature）
-
规则门槛 （warning / error / 阻挡合并）
-
Baseline 策略 （是否允许、收敛节奏）
-
CI 执行范围 （全量或仅变更文件）
-
代码审查口径 （review 必查项）
Deliverables (完成后交付物)
-
.editorconfig 与命名规范文档
-
detekt.yml / ktlint 配置与 baseline
-
CI style gate （lint/detekt/ktlint）
-
PR 模板 （包含风格验收条目）
-
规则变更记录 （说明原因与影响）
Style Gate (验收门槛)
./gradlew lint ./gradlew detekt ./gradlew ktlintCheck
旧项目使用 baseline 时，必须在 PR 说明中写明本次减少了哪些 baseline 项目。
Naming Conventions (命名规则)
类型 规则 范例
Class / Interface PascalCase
UserRepository , Drawable
Function / Method camelCase
getUserById() , onClick()
Variable / Property camelCase
userName , isLoading
Constant (top-level/object) SCREAMING_SNAKE_CASE
MAX_RETRY_COUNT
Package lowercase (no underscores) com.example.feature.auth
@Composable Function PascalCase
LoginScreen() , UserCard()
Backing Property _camelCase
private val _uiState
Compose Specific
// ✅ Composable 函数用 PascalCase (像 Class) @Composable fun UserProfileCard(user: User, modifier: Modifier = Modifier) { }
// ✅ State holder 用 remember + camelCase val scrollState = rememberScrollState()
// ✅ Event callback 用 on 前缀 onUserClick: (User) -> Unit
Detekt Configuration
安装与设置
// build.gradle.kts (project-level) plugins { id("io.gitlab.arturbosch.detekt") version "<project-verified-version>" }
// build.gradle.kts (app-level) detekt { buildUponDefaultConfig = true config.setFrom("$rootDir/config/detekt/detekt.yml") baseline = file("$rootDir/config/detekt/baseline.xml") }
建议规则集 (detekt.yml)
complexity: LongMethod: threshold: 30 LongParameterList: functionThreshold: 6 constructorThreshold: 8
naming: FunctionNaming: excludes: ['/composables/'] # Compose 用 PascalCase
style: MaxLineLength: maxLineLength: 120 WildcardImport: active: true MagicNumber: ignorePropertyDeclaration: true ignoreCompanionObjectPropertyDeclaration: true
Baseline 机制 (旧项目适用)
生成 baseline，忽略现有问题
./gradlew detektBaseline
之后只检查新代码的违规
./gradlew detekt
Ktlint Configuration
安装
// build.gradle.kts plugins { id("org.jlleitschuh.gradle.ktlint") version "<project-verified-version>" }
ktlint { android.set(true) outputColorName.set("RED") }
.editorconfig (与 IDE 同步)
[*.{kt,kts}] max_line_length = 120 indent_size = 4 insert_final_newline = true
Ktlint specific
ktlint_standard_no-wildcard-imports = enabled ktlint_standard_trailing-comma-on-call-site = enabled ktlint_standard_trailing-comma-on-declaration-site = enabled
Documentation Standards (KDoc)
何时该写
-
✅ Public API (SDK, Library)
-
✅ 复杂的业务逻辑
-
✅ 非直观的参数或回传值
-
✅ 重要的设计决策
何时不该写
-
❌ 自解释的代码 (e.g., fun getUserName(): String )
-
❌ 覆写的方法 (继承父类文档)
-
❌ 简单的 CRUD 操作
范例
/**
- 根据优先级排序并过滤过期的任务。
- @param tasks 待处理的任务列表
- @param now 用于判断过期的时间点，默认为当前时间
- @return 依优先级排序的有效任务，过期任务会被过滤
- @throws IllegalArgumentException 如果 tasks 包含 null 元素 */ fun filterAndSort(tasks: List<Task>, now: Instant = Instant.now()): List<Task>
Quick Checklist
- Required Inputs 已填写并冻结（范围/门槛/baseline）
Naming & Style
-
命名是否遵循上述规则？
-
Compose 函数是否用 PascalCase？
-
是否有 Magic Number？
Structure
-
函数是否过长 (> 30 行)？
-
参数是否过多 (> 6 个)？
-
是否有 God Class 倾向？
Safety
-
Nullable 处理是否安全？
-
是否有潜在的 NPE？
-
异常处理是否完善？
Compose Specific
-
Modifier 是否为第一个可选参数？
-
State 是否正确 hoist？
-
是否有 unstable 的参数导致不必要重组？
-
Style Gate（lint/detekt/ktlintCheck）已执行并通过