Coding Style Conventions

Instructions

當需要建立、檢視、強化 Kotlin 風格與靜態檢查規則時載入。本 skill 只談「規則本身」與「IDE/CI 整合方式」；CI workflow 框架由 @releaseautomation 負責，平台升級由 @platformmodernization_2026 負責。

When to Use

Scenario A：新專案建立規範
Scenario C：舊專案現代化基準
統一 Compose 命名與 modifier 順序
加入 Compose Stability / Compiler Metrics 至 review
解決多模組 SuppressLint 失控

When NOT to Use

CI workflow 設計與並行策略 → @release_automation
Compose UI 設計（Spacing、Theme）→ @uiuxengineering
解決效能瓶頸 → @deepperformancetuning

Example Prompts

「我想升 Detekt 到 1.25，新規則我該開哪些？」
「Compose Stability 的 strong-skipping 怎麼配？」
「PR review 想自動化，KDoc 與命名規則的 checklist」
「多模組 baseline.xml 怎麼管才不爆增？」

Workflow

.editorconfig + Ktlint 1.4+ 規則對齊 IDE。
Detekt 1.25+ 套自訂 yml + 可選 baseline。
Compose Compiler Metrics 啟用，輸出至 build/compose-metrics。
SuppressLint 政策：以 lint-baseline.xml 收容歷史，新代碼禁止 SuppressLint 而無註解理由。
Code Review Checklist 嵌入 PR 模板。

Practical Notes (2026-04)

工具	版本	備註
Detekt	1.25+	含 `detekt-formatting`（Ktlint 規則整合）
Ktlint	1.4+	trailing comma 預設啟用
Compose Compiler	Kotlin 2.1 內建 plugin	`composeOptions` 已不需要
Strong Skipping	預設啟用（Compose Compiler 1.5.4+）	大幅減少不必要重組
Lint	AGP 8.7+ 內建	與 Detekt 互補不衝突

Minimal Template

規範範圍: <new project | legacy module | single PR>
工具: detekt + ktlint + lint
強制機制: pre-commit hook + CI gate
特例豁免: lint-baseline.xml（凍結） + SuppressLint with TODO comment（限期）
驗收: Quick Checklist

Naming Conventions

類型	規則	範例
Class / Interface	PascalCase	`UserRepository`
Function	camelCase	`getUserById()`
@Composable Function	PascalCase	`LoginScreen()`
Variable / Property	camelCase	`userName`, `isLoading`
Constant（top-level / object）	SCREAMINGSNAKECASE	`MAXRETRYCOUNT`
Package	lowercase	`com.example.feature.auth`
Backing Property	`_camelCase`	`private val _uiState`
Test Method	backtick + 中英文皆可	` clicking save emits success`()` `

Compose 命名與 modifier 順序

// ✅ 簽章順序：必填 → modifier → 可選 → callback → state slots
@Composable
fun UserCard(
    user: User,
    modifier: Modifier = Modifier,
    elevation: Dp = 2.dp,
    onClick: (User) -> Unit = {},
    actions: @Composable RowScope.() -> Unit = {},
) { /* ... */ }

// ❌ Modifier 不在第二個位置、不是 Modifier.Companion
fun UserCard(user: User, onClick: () -> Unit, m: Modifier)

// Modifier 鏈順序：size → shape/background → padding → behavior（clickable/scroll）→ semantics
Modifier
    .size(64.dp)
    .clip(RoundedCornerShape(8.dp))
    .background(MaterialTheme.colorScheme.surface)
    .padding(8.dp)
    .clickable(onClick = onClick)
    .semantics { contentDescription = "user card" }

Detekt 1.25+

// build.gradle.kts (root)
plugins {
    id("io.gitlab.arturbosch.detekt") version "1.25.0"
}

allprojects {
    apply(plugin = "io.gitlab.arturbosch.detekt")
    detekt {
        buildUponDefaultConfig = true
        config.setFrom("$rootDir/config/detekt/detekt.yml")
        baseline = file("$rootDir/config/detekt/baseline.xml")
        autoCorrect = false   // 由 ktlint 處理格式化
    }
    dependencies {
        "detektPlugins"("io.gitlab.arturbosch.detekt:detekt-formatting:1.25.0")
        "detektPlugins"("com.twitter.compose.rules:detekt:0.0.26")
    }
}

# config/detekt/detekt.yml
complexity:
  LongMethod: { threshold: 30 }
  LongParameterList: { functionThreshold: 6, constructorThreshold: 8 }
  CyclomaticComplexMethod: { threshold: 12 }
  TooManyFunctions: { thresholdInClasses: 15 }

style:
  MaxLineLength: { maxLineLength: 120 }
  WildcardImport: { active: true }
  MagicNumber:
    ignorePropertyDeclaration: true
    ignoreCompanionObjectPropertyDeclaration: true
  ReturnCount: { max: 3 }

naming:
  FunctionNaming:
    ignoreAnnotated: ['Composable']
  TopLevelPropertyNaming:
    constantPattern: '[A-Z][_A-Z0-9]*'

# Twitter Compose Rules
Compose:
  ComposableNaming: { active: true }
  ModifierComposable: { active: true }
  ModifierMissing: { active: true }
  ModifierNaming: { active: true }
  ParameterNaming: { active: true }
  PreviewPublic: { active: true }
  RememberMissing: { active: true }
  UnstableCollections: { active: true }
  ViewModelForwarding: { active: true }

Baseline 政策

第一次接舊專案：./gradlew detektBaseline 凍結。
baseline.xml 每季審視一次，刪除已修復項目；不允許無限增長。
新模組禁止 baseline；違規必須當下處理。

Ktlint 1.4+

plugins {
    id("org.jlleitschuh.gradle.ktlint") version "12.1.2"
}
ktlint {
    version.set("1.4.1")
    android.set(true)
    ignoreFailures.set(false)
    reporters {
        reporter(org.jlleitschuh.gradle.ktlint.reporter.ReporterType.SARIF)
    }
}

# .editorconfig
root = true

[*]
end_of_line = lf
insert_final_newline = true
charset = utf-8

[*.{kt,kts}]
indent_size = 4
max_line_length = 120
ij_kotlin_allow_trailing_comma = true
ij_kotlin_allow_trailing_comma_on_call_site = true

ktlint_standard_no-wildcard-imports = enabled
ktlint_standard_trailing-comma-on-call-site = enabled
ktlint_standard_trailing-comma-on-declaration-site = enabled
ktlint_standard_function-signature = enabled
ktlint_function_signature_body_expression_wrapping = always
ktlint_standard_property-naming = enabled

Compose Stability / Compiler Metrics

// build-logic 中的 AndroidComposeConventionPlugin
extensions.configure<ComposeCompilerGradlePluginExtension> {
    metricsDestination.set(layout.buildDirectory.dir("compose-metrics"))
    reportsDestination.set(layout.buildDirectory.dir("compose-reports"))
    stabilityConfigurationFile.set(rootProject.file("config/compose/stability.conf"))
}

# config/compose/stability.conf — 標記第三方/不可變類型為 stable
java.time.Instant
java.util.UUID
com.example.network.dto.*Response
kotlinx.collections.immutable.*

Strong Skipping：Compose Compiler 1.5.4+ 預設啟用；非 stable 但相同 instance 的參數仍會 skip。

CI 檢查：

# 偵測 unstable composable 數
unstable=$(grep -c "unstable params" app/build/compose-reports/*.txt || true)
[ "$unstable" -lt "20" ] || { echo "Unstable composable 數 $unstable 超標"; exit 1; }

SuppressLint 多模組策略

Lint baseline 路徑：每模組 lint-baseline.xml，避免 root 一個巨型檔。
新增 SuppressLint 規則：必須附原因 + 期限 TODO，例如：

``kotlin @SuppressLint("MissingPermission") // FIXME(2026-Q3): 由 PermissionManager 統一處理 ``

CI 阻擋無理由 SuppressLint：寫個 detekt rule 或 grep 檢查。

KDoc Standards

寫：public API、複雜業務邏輯、非直觀參數、重要設計決策。不寫：自解釋程式碼、覆寫方法、簡單 getter。

/**
 * 依優先級排序並過濾過期任務。
 *
 * @param tasks 待處理任務列表
 * @param now 判斷過期的時間點，預設為當前時間
 * @return 依優先級排序的有效任務
 * @throws IllegalArgumentException 若 tasks 含 null
 */
fun filterAndSort(tasks: List<Task>, now: Instant = Instant.now()): List<Task>

Code Review Checklist

Naming & Style

遵循命名規則
Composable 為 PascalCase 且第一個可選參數為 modifier: Modifier = Modifier
無 magic number（或加註解理由）

Structure

函數 ≤ 30 行
參數 ≤ 6 個（建構式 ≤ 8）
無 God Class（單檔 ≤ 500 行為原則）

Safety

Nullable 處理採 safe call / requireNotNull
不吞 exception；至少 log 並上報
無 runBlocking 在主執行緒

Compose

modifier 在第二個位置且名為 modifier
State 正確 hoist（screen 持有，children 無狀態）
Unstable 參數已標 stable 或改用 immutable collection
remember { ... } key 正確
Preview 為 @Preview 私有 composable

Cross-Skill References

@project_bootstrapping：Convention Plugin 接 Detekt/Ktlint。
@release_automation：將 detekt/ktlint 加入 CI gate；本 skill 提供規則檔。
@uiuxengineering：Compose Theme/Spacing 設計與本 skill 的命名/順序一致。
@platformmodernization2026：升 Kotlin 2.1 後 ktlint/detekt 版本同步升級。

Quick Checklist

.editorconfig 與 ktlint 1.4+ 規則對齊 IDE
Detekt 1.25+ + detekt-formatting + Twitter Compose Rules 啟用
Compose Compiler Metrics 啟用，CI 監看 unstable composable 數
Stability config 收容第三方不變類型
lint-baseline.xml 每季審視，禁止無限增長
SuppressLint 必有 TODO + 期限
PR template 嵌入 Code Review Checklist
規範變更與功能變更分開 PR

Coding Style Conventions

Installation

Similar popular skills

Also in this package

Agent compatibility

Package contents

History

SKILL.md

Coding Style Conventions

Instructions

When to Use

When NOT to Use

Example Prompts

Workflow

Practical Notes (2026-04)

Minimal Template

Naming Conventions

Compose 命名與 modifier 順序

Detekt 1.25+

Baseline 政策

Ktlint 1.4+

Compose Stability / Compiler Metrics

SuppressLint 多模組策略

KDoc Standards

Code Review Checklist

Naming & Style

Structure

Safety

Compose

Cross-Skill References

Quick Checklist