mirror of https://github.com/luongnv89/claude-howto.git synced 2026-04-21 21:45:58 +02:00

Files

T

Luong NGUYEN 89e89d4aa3 feat(zh): add Chinese translations in zh/ directory

Add Chinese (Simplified) translations for all documentation, organized
under a dedicated zh/ directory that mirrors the English folder structure.

Co-authored-by: tanqingkuang <tanqingkuang@users.noreply.github.com>

Translations originally contributed by @tanqingkuang in #45.
Restructured from *-CN.md suffix pattern into zh/ directory to prevent
the EPUB builder (scripts/build_epub.py collect_folder_files) from
picking up Chinese files via glob("*.md") inside module folders.

2026-04-06 23:08:54 +02:00

4.2 KiB

Raw Permalink Blame History

面向 AI 代码生成的整洁代码规则

这些规则用于指导代码生成，帮助产出可维护、专业水准的代码。

有意义的命名

使用能体现意图的名称，说明它为什么存在
避免误导性命名和无意义区分，例如 data、info、manager
使用可读、可搜索的名称
类名使用名词，例如 UserAccount、PaymentProcessor
方法名使用动词，例如 calculateTotal、sendEmail
避免脑内映射和编码风格命名，例如匈牙利命名法、前缀

函数

保持函数短小精炼，理想情况下少于 20 行
只做一件事，遵循单一职责原则
每个函数只处理一个抽象层级
限制参数数量，理想为 0-2 个，最多 3 个，避免布尔标志参数
不要产生副作用，函数应该做它名字所说的事
将命令与查询分离，命令修改状态，查询返回信息
优先使用异常而不是错误码

注释

代码本身应该尽量可自解释，能不写注释就不写
好的注释包括：法律信息、警告、TODO、公共 API 文档
坏的注释包括：重复、误导，或者只是解释糟糕的代码
不要注释掉代码，直接删除，版本控制会保留历史
如果你需要写注释，先考虑重构代码

格式化

保持文件小而聚焦
垂直格式化：相关概念放近一些，空行分隔不同概念
水平格式化：限制行长度在 80-120 个字符之间
使用一致的缩进和团队风格
将相关函数分组放在一起

对象与数据结构

对象：通过抽象隐藏数据，通过方法暴露行为
数据结构：暴露数据，尽量少提供行为
迪米特法则：只和直接朋友说话，避免 a.getB().getC().doSomething()
不要毫无节制地通过 getter/setter 暴露内部结构

错误处理

使用异常，不要使用返回码或错误标志
代码可能失败时，先写 try-catch-finally
在异常信息中提供上下文
不要返回 null，改为返回空集合或使用 Optional/Maybe
不要把 null 作为参数传入

类

小类应按职责衡量，而不是按行数衡量
单一职责原则：只有一个改变原因
高内聚：类变量被多数方法使用
低耦合：类之间依赖尽量少
开闭原则：对扩展开放，对修改关闭

单元测试

快速、独立、可重复、自我验证、及时（F.I.R.S.T.）
每个测试一个断言，或只验证一个概念
测试代码质量应与生产代码质量一致
测试名称要可读，清楚描述正在测试什么
遵循 Arrange-Act-Assert 模式

代码质量原则

DRY（Don't Repeat Yourself）：不要重复
YAGNI（You Aren't Gonna Need It）：不要为假设中的未来提前构建
KISS（Keep It Simple）：避免不必要的复杂度
童子军规则：让代码比你接手时更干净

应避免的代码坏味道

函数或类过长
重复代码
死代码（未使用的变量、函数、参数）
特性依恋（方法更关心别的类）
不恰当的亲密关系（类彼此了解过多）
过长的参数列表
原始类型偏执（过度使用原始类型而不是小对象）
switch/case 语句（考虑使用多态）
临时字段（类变量只在某些时候才使用）

并发

将并发代码与其他代码隔离
限制同步/加锁数据的作用域
使用线程安全集合
保持同步区块尽量小
了解你的执行模型和原语

系统设计

将构建和使用分离，例如通过依赖注入
复杂对象创建时使用工厂、构建器
面向接口编程，而不是面向实现编程
优先组合而不是继承
设计模式只在它们简化问题时使用，不要为了炫技而使用

重构

持续重构，不要攒成大批量一次做完
重构前后都要保证测试通过
小步前进，每次只改一处
常见重构包括：提取方法、重命名、移动、内联

文档

自说明代码 > 注释 > 外部文档
公共 API 需要清晰文档
文档中要包含示例
文档尽量靠近代码，理想情况下就在代码里

核心理念：代码被阅读的次数是编写次数的 10 倍。优化可读性和可维护性，而不是追求花哨。

4.2 KiB Raw Permalink Blame History Unescape Escape