// Use when writing, reviewing, or modifying source code in any language (Java / TypeScript / JavaScript / Dart / Python / Kotlin / Go / Vue / React 等). 跨语言通用编码铁律 7 条 + 注释三档,语言专属 skill (java-coding-standards / korepos-backend-service 等) 在此基础上叠加。MUST 自动触发,不需用户显式要求。
[HINT] Download the complete skill directory including SKILL.md and all related files
| name | coding-standards-common |
| description | Use when writing, reviewing, or modifying source code in any language (Java / TypeScript / JavaScript / Dart / Python / Kotlin / Go / Vue / React 等). 跨语言通用编码铁律 7 条 + 注释三档,语言专属 skill (java-coding-standards / korepos-backend-service 等) 在此基础上叠加。MUST 自动触发,不需用户显式要求。 |
适用于一切源码语言。语言专属规则(如
java-coding-standards的阿里黄山版独占条款、korepos-backend-service的 Flutter backend 规则)在此基础上叠加,不重复。触发链路:
coding-standards-common(通用) →{language}-coding-standards(语言专属)。任何源码 Edit/Write 前先满足本 skill 的 7 条铁律,再走语言专属。
MAX_RETRY_COUNTUpperCamelCase;方法/变量名 lowerCamelCase(语言惯例允许时)is_ / get_ 前缀(JSON / POJO 反序列化兼容性问题)XxxImpl;数据/传输/展示对象用 XxxDO/DTO/VO,禁混用get,获取列表 list,统计 count,插入 save/insert,删除 remove/delete,修改 update_xxxStep 私有方法,主方法只做编排 + 事务 + 日志orchestrator 或原子能力层common/ 或等价的原子能力目录,禁复制粘贴0 / 1 / -1、true / false、空串 ""、空集合、单元测试断言字面量state == 3、item_type=1)MAX_RETRY = 3)用 const 并写一行 WHY 注释说明阈值依据== / equals;金额类用 BigDecimal 或差值 ≤ 容差(POS 场景常用 ±0.005)立场:类、方法、核心代码块都必须写注释,但每档都有「简要」上限。优先讲 WHY、当前职责、约束;不允许把变更历史、设计史、实现步骤流水写进源码。
git-commit-standards 控制(默认中文 body),设计 / bug / 知识图谱文档语言由对应 doc skill 控制。判断准绳:不要把"英文是行业默认"当成默认,不要把"中文更亲切"当成默认,也不要把"原文件是英文"当成默认。沟通语言就是默认——读你代码的下一个人多半就是这次会话里的协作者。
写清:
写清:
以下场景必加行内注释:
// 评分阈值:>=70 视为通过)// 用 ConcurrentHashMap 因多线程并发)// 最大修正次数,超过不再重试)// 向量库不可用时降级为纯 LLM 分析)// TODO(zhangkai): 等 v1.22 接入新协议后删除)[BUGFIX] / [DEPRECATED] / [ADDED] / 日期标记 / PR 号 → 进 git commit bodygetUser: 获取用户)bugfix-coding-style 冲突的实现步骤复盘立场:改了逻辑就要校对周边注释。过期注释比没有注释更糟——它会主动误导下一个读你代码的人;历史版本说明 / 废话注释会污染文件、消耗后续阅读者的注意力。改到哪,清到哪。
发现以下任意形态,改到该方法 / 代码块时一并删干净,不留痕:
// [BUGFIX] xxx、// [DEPRECATED]、// [ADDED v1.2]、// 2024-03-15 修改、// PR#1234 调整// 原本用 HashMap,后改为 ConcurrentHashMap、// 这里之前有个 bug,现在修了、// v1.0 写法,v2.0 重构// 兼容老版本 xxx(老版本已下线)、// 为了 v1.x 用户保留(已不需要)// 暂时这么写、// 待优化(没有 owner / 没有触发条件,本质是垃圾 TODO)// / /* */ 包起来的死代码,直接删这些信息属于 git commit body / design doc / bug doc,不属于源码。源码只回答"现在是什么、为什么这么写"。
// getUser: 获取用户、/** 用户ID */ Long userId(字段名已自解释)i++; // i 加 1、return null; // 返回 null// xxx、// TODO(无内容)、/** */ 空 doc 块bugfix-coding-style skill 完全对齐:bug 修复 PR 里禁止新增任何"修了什么 bug / 之前怎么错的"的源码注释,要写进 commit message 或 bug doc类 1–3 行,方法 1–2 行,代码块 1 行。写不下就说明你想塞实现细节,那部分应该进文档而不是源码。
catch 必须处理或显式往上抛,禁空 catche.getMessage()(等价于把堆栈丢了)try-catch 做流程控制finally 中禁 return(会吞掉 try 的返回值或异常)catch 块必须手动回滚事务common/services/ / common/backend_infra/services/ 等)| 通用 skill(本文件) | 语言 / 框架专属 skill |
|---|---|
| 命名表意 / 函数原子 / 层次分明 / 零魔法值 / 注释三档 / 异常不静默 / 删冗余 | java-coding-standards: 包装类比较、SimpleDateFormat、SLF4J 占位符、HashMap 容量、BigDecimal 比较、JDK8+ DateTimeFormatter、SQL 列名规范、索引规则等 Java / 数据库独占条款 |
| 同上 | korepos-backend-service: backend 目录结构、BackendInfra 边界、一接口一 service、Service 禁裸 SQL、跨 feature 业务原子能力、长方法拆 step、DB 字段值枚举绑定等 Flutter backend 独占条款 |
| 同上 | bugfix-coding-style: 禁源码内变更日志 / 函数头不堆复盘 / 复杂逻辑就近 WHY(本 skill §5.4 与之完全对齐) |
| 同上 | arch-lint: Flutter 5 类架构违规自动检测 |
触发顺序:任何源码 Edit/Write 前,先满足本 skill 的 7 条铁律 → 再走语言/框架专属 skill 的独占条款 → 最后由 coding-violation-log 在用户纠错时登记差异。
写代码前 / 提交前过一遍以下 7 项,有 ❌ 必须改:
data / info / temp?