《代码整洁之道》读后：干净代码不是洁癖，是职业素养

《代码整洁之道》读后：干净代码不是洁癖，是职业素养

大三上学期，我在一次代码 Review 中被队友"教育"了整整二十分钟。原因很简单：我写的接口函数长达 180 行，变量名叫 data、temp、flag，错误处理散落在各个角落。那时候我的内心独白是："能跑不就行了吗？"

后来导师扔给我一本《代码整洁之道》（Clean Code），说："看完再跟我说话。"

一、最冲击我的三个观点

1. 函数应该做一件事，做好这件事，只做这件事

书里有一句话我到现在都记得：

"Functions should do one thing. They should do it well. They should do it only."

我之前写函数的方式，基本上是"把功能堆进去就行"。比如下面这段代码，是我大二时写的"用户登录 + 权限校验 + 日志记录"一体函数（真实历史代码，至今不忍直视）：

def handle_user_request(uid, pwd, role):
    import hashlib, sqlite3, datetime, logging
    if not uid or not pwd:
        return {"error": "missing field"}
    conn = sqlite3.connect("user.db")
    cur = conn.cursor()
    cur.execute("SELECT password, role FROM users WHERE uid=?", (uid,))
    row = cur.fetchone()
    if not row:
        conn.close()
        return {"error": "user not found"}
    if row[0] != hashlib.md5(pwd.encode()).hexdigest():
        conn.close()
        return {"error": "wrong password"}
    if row[1] != role:
        conn.close()
        return {"error": "role mismatch"}
    now = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")
    cur.execute("INSERT INTO login_log(uid, time) VALUES(?,?)", (uid, now))
    conn.commit()
    conn.close()
    logging.info(f"User {uid} logged in at {now}")
    return {"success": True, "role": row[1]}

三个问题揉在一个函数里：数据访问、业务逻辑、日志基础设施。哪天要换数据库、要改密码加密方式、要加登录通知，都得动这个函数。

按照书中的理念重构之后：

from dataclasses import dataclass

@dataclass
class User:
    uid: str
    password_hash: str
    role: str

class AuthService:
    def __init__(self, user_repo, password_hasher, logger):
        self._users = user_repo
        self._hasher = password_hasher
        self._logger = logger

    def authenticate(self, uid: str, pwd: str, expected_role: str) -> dict:
        user = self._users.find_by_id(uid)
        if not user:
            return {"error": "user not found"}
        if not self._hasher.verify(pwd, user.password_hash):
            return {"error": "wrong password"}
        if user.role != expected_role:
            return {"error": "role mismatch"}
        self._logger.record_login(uid)
        return {"success": True, "role": user.role}

函数变短了，每个函数只有一个变更理由。这是单一职责原则在函数级别的最直观体现。

2. 好名字胜过注释

书里有一句很"极端"的话："如果函数名需要注释来解释，那这个名字就起错了。"

我以前的习惯是：

# 处理数据
def proc(d):
    pass

# 检查状态
def chk(s):
    pass

后来看了自己三个月前写的代码，完全想不起来 proc 是 process 还是 proceed，chk 是 check 还是 chunk。

现在我的底线是：缩写只在团队有共识的情况下使用，变量名宁可长也不要让别人猜。比如：

# 之前
def calc(x, y):
    r = x * 0.1 + y * 0.05
    return r

# 之后
DISCOUNT_RATE_BASE = 0.10
DISCOUNT_RATE_MEMBER = 0.05

def calculate_order_discount(base_amount, member_level_bonus):
    discount = base_amount * DISCOUNT_RATE_BASE + member_level_bonus * DISCOUNT_RATE_MEMBER
    return round(discount, 2)

多打几个字符，省下的是半个小时的"这变量到底啥意思"的琢磨时间。

3. 错误处理就是一件事

书中强调：错误处理是函数要做的一件事，不应该混杂在正常的业务逻辑里。 Try-Catch 块里的内容，应该抽成独立的函数。

我现在的做法是，在 Service 层抛出有意义的异常，在 API 层统一捕获：

class OrderService:
    def create_order(self, user_id: str, item_ids: list) -> "Order":
        if not self._inventory.is_available(item_ids):
            raise InsufficientInventoryError(item_ids)
        if not self._user_repo.exists(user_id):
            raise UserNotFoundError(user_id)
        return self._persist_order(user_id, item_ids)

@app.post("/orders")
def api_create_order(req: "CreateOrderRequest"):
    try:
        order = order_service.create_order(req.user_id, req.item_ids)
        return {"order_id": order.id}
    except InsufficientInventoryError as e:
        raise HTTPException(status_code=409, detail=str(e))
    except UserNotFoundError as e:
        raise HTTPException(status_code=404, detail=str(e))

业务逻辑干净了，错误处理也集中了。

二、我有保留意见的地方

书里并不是所有观点我都照单全收。比如"函数不能超过 4 行"这个建议，我觉得在实际项目中要辩证看待。

有些业务本身就很复杂，强制拆成 N 个微小函数，反而会让代码跳转来跳转去，阅读体验更差。我现在的准则是：函数短是好事情，但不要为了短而短。语义清晰 > 行数少。

另外一个有争议的点是"注释有害论"。书的立场是"好代码自解释，不需要注释"。但我认为：公共 API、复杂算法、业务规则的意图，适当的注释是非常有价值的。关键是注释要说明"为什么"，而不是"是什么"——"是什么"应该由代码本身表达。

# 好的注释：说明业务背景
# 根据《电商法》第35条，促销订单需在30分钟内完成库存预占
INVENTORY_HOLD_SECONDS = 1800

# 坏的注释：重复代码本身
# 设置库存预占时间为1800秒
INVENTORY_HOLD_SECONDS = 1800

三、读完之后，我的代码发生了什么变化

最直观的变化：PR 被要求修改的次数明显少了。

以前队友 Review 我的代码，反馈通常是"这个函数能干啥"、"这个变量是干嘛的"、"这里为什么要用 flag=3 来判断"。现在反馈更多是关于架构设计和边界条件的讨论，而不是命名和可读性的 basics。

另外一个变化是：重构不再是一件"专门安排时间去做"的事情，而是写代码过程中的自然动作。 书中说的 "Leave the campground cleaner than you found it"（让营地比你来的时候更干净），已经成为我的编码习惯——每次改一个文件，顺手把看不顺眼的地方整理一下，不用等到"重构 sprint"。

四、推荐给谁读？

如果你是大三下/研0，正在找实习或准备校招，我强烈推荐把这本书列入必读清单。面试时"讲讲你最近读了什么技术书"这类问题，能把《代码整洁之道》里的具体例子讲出来，比说"我熟悉 Java/Python"有说服力得多。

但也要提醒一句：不要把它当圣经，要当工具箱。 书里的一些实践（比如"每个函数不超过 4 行"）在大型工程里需要灵活处理。核心是理解背后的 Why：代码是写给人看的，顺便让机器执行。

---

以上是我个人读《代码整洁之道》的真实体会，不是书评，是踩坑记录。如果你的代码也曾经被队友"教育"过，那咱们是一类人。