编程风格

以下内容全部围绕 “降低复杂度、减少心智负担、提高维护性” 展开。

适用所有语言（Python/Go/JS/TS/Java/C++）。

if 只做布尔判断，不写长逻辑；异常情况提前返回（Guard Clauses）

✅ 保留 if 只用于判断，而不是执行大量逻辑

❌ 不要这样：

if a and b and c:
    # 非常长的大段代码
    # ……

✅ 推荐提前退出（减少嵌套）

条件成立则 return、exit、raise、break、continue 等等

if not valid:
    return None   # 或 raise 或 exit 或 continue 等等

# 主逻辑更清晰
process()
save()

✅ if 内的代码超过 5～8 行：必须抽函数

这对可读性、测试性都是巨大收益。

避免写只使用一次的环境变量、配置变量

❌ 不推荐：

ROOT = "/var/data"          # 只用一次
path = ROOT + "/user.json"

✅ 推荐：

直接写在使用的地方，除非是真配置（可复用）。

优先使用函数式编程（函数为一等公民）

✅ 函数可作为参数、返回值、变量

例如：

把逻辑封装成回调
传递 lambda/map/filter
使用高阶函数减少重复逻辑

好处：

更少副作用
更好测试
更容易并发/并行
模块化更自然

✅ 函数必须有返回值，没有返回值则返回 None 或者 Bool

避免深层嵌套：超过 3 层就要拆

例子：

if a:
    if b:
        if c:
            do()

替换为：

if not a or not b or not c:
    return

do()

变量生命周期越短越好

只在用的地方定义，不要提前 20 行声明变量。

每个函数控制在 20～30 行内

超过 30 行，一般意味着职责不够单一。

避免副作用：函数只做一件事且无隐藏行为

❌ 函数内部偷偷修改全局变量
❌ 函数内部读写磁盘、网络（除非就是 IO 函数）
❌ 函数内部改变传入的对象结构（不可预期）

✅ 函数输入 -> 输出可预测

魔法数字禁止出现（Magic Numbers）

❌

if timeout > 1200 {

✅

const MAX_TIMEOUT = 1200
if timeout > MAX_TIMEOUT {

switch-case（或 match）优先于复杂 if-else 链

if-else 链是代码坏味道。

避免写万能函数；越通用的函数，越难维护

❌ utils.py 里塞一堆无关函数
❌ doEverything(data)
❌ 过度抽象

✅ 用 “可组合的小函数” 代替 “一个大而通的函数”。

日志要精简但结构化（可检索）

推荐格式：

INFO: action=DeleteUser user_id=33 cost=120ms result=ok

JSON 格式更佳。

错误信息必须包含上下文，否则无法排查

❌

Error: failed

✅

Error: db query failed, user_id=233, sql=xxx

优先不可变数据结构（immutable）

好处：

更容易推理
更少出 bug
更适合集群/并发场景

循环中避免创建临时大对象或重复运算

如：不要每次循环都正则编译。

接口（函数）参数不得超过 3 个

超过 3 个就包装成对象 / 结构体 / dataclass。

模块之间保持低耦合，高内聚

低耦合：

模块之间依赖少、接口清晰

高内聚：

模块内部功能相关性强

便于重构和拆模块

优先显式，而不是隐式（Explicit > Implicit）

例如：

Python 里优先写清楚参数名
变量名不要缩写，除非是数学变量
不要省略 return/await 之类

写代码前先写结构

先想：

数据结构
输入输出
责任划分

再写代码。

能减少 50% 重构。

早失败（Fail Fast）、早暴露问题

参数校验提前做
内部断言
遇到异常立即报错，而不是默默吞掉

保持一致性比聪明更重要（Consistency > Cleverness）

团队协作最重要的不是“写得多厉害”，是“写得大家都看得懂”。

数据格式：数据保存到数据库中

Python：

SQLAlchemy ORM Create 只接收 dict 或者 list[dict]
FastAPI 只接收 JSON 或者 JSON 列表

原因：

字段对应，强一致性，避免数据保存错误
有些 ID 是自增的，避免 ID 冲突

日期时间格式

统一使用 ISO 8601 格式 YYYY-MM-DD HH:MM:SS

示例：2021-01-01 00:00:00