SuperAPI AI 工具集

awesome-code-standards

编程与开发

查看项目

更新于 10-15 23:45

技能介绍

用途:在启动新项目或模块、按团队约定重构、配置或更新 lint/format/type-check 规则、统一代码库约定、新人上手说明约定、强制命名与结构一致性时,应用一致的命名、结构与模式,让代码在团队内可读可维护。审查具体 diff 属于 awesome-code-review,仓库级注释清理属于 awesome-code-cleanup,错误契约设计属于 awesome-error-standards。

核心原则:可读性优先;KISS;DRY;YAGNI;优先不可变,避免修改参数或共享状态;需要时用展开或复制生成新对象。

工作流程:先扫描现有代码发现约定(命名大小写、文件布局、导入风格、测试模式),检查 CONTRIBUTING、.eslintrc、.prettierrc、editorconfig;按维度统计(引号、缩进、命名大小写),多数派即为约定,少数派记为问题,平局则询问而非自行决定。再对照约定列出违规,给出具体修复建议(重命名、抽函数、补类型、修格式),每条建议尽量只做一处逻辑修改;项目已有的例外要记录,而不是无上下文地“修复”。

命名:函数用动词加名词,变量名要描述性强;真正常量用 UPPER_SNAKE(或项目约定);类型与接口用 PascalCase,可按角色加 CreateUserRequest、UserResponse 等后缀;组件文件 PascalCase,工具与 hooks 用 camelCase,类型文件按项目用 .types 或 .d。规则是遵循各语言官方风格:Python 用 PEP 8,Go 用 MixedCaps,Rust 用 RFC 430,Java/Kotlin 与 C# 各有其约定。

不可变:用展开生成新引用,避免直接改对象或数组;其他语言同规则不同机制,如 Python 不用可变默认参数、Go 注意切片底层数组共享、Rust 默认不可变、Java 用 record 与 List.copyOf、C# 用 record 加 with。

错误处理:校验后再抛出或返回带上下文的信息,不吞异常;Python 抛具体异常并从 err 链接重抛,Go 用 %w 包装,Rust 返回 Result 并用 ? 传播,Java 每种失败一个异常类型,C# 捕获具体异常并用裸 throw 重抛。

异步与并发:独立任务并行执行,每个并发单元可取消。

类型安全:显式类型,不用 any;无检查器的动态语言在信任边界用 schema 校验。

注释与文档:解释为什么而非是什么;用纯 ASCII 标点;注释用平实动词;不写代码已声明的值;不用分节横线;不写被注释掉的代码。文档注释补类型无法表达的契约,按语言自身格式。

文件与项目结构:遵循现有布局;每文件一个主要导出(除非用 barrel);导入按标准库、第三方、本地分组。后端分层:DTO、领域、持久化三模型分离;按需判定层归属;横切关注点只在边缘做一次;错误不知道传输层;契约优先。

须修复的代码坏味:函数超过约 50 行、嵌套 5 层以上、魔法数字、参数过长、重复逻辑。框架特定正确性以该框架官方文档为准,例如 React 的 {count && <X/>} 会渲染 0、组件内定义组件、可由 props 派生的状态放进 useState 加 useEffect。前端渲染与动效只动 transform 与 opacity,避免同帧读写布局,滚动动画优先 animation-timeline。前端架构采用功能优先的文件夹。

缺失事实:资料未提供收费、价格或平台支持信息。