写出能长期使用的代码：一些实用的经验

每个程序员都记得自己第一次让代码成功运行时的感觉。屏幕上出现结果，问题得到解决，那种兴奋感让人难忘。但是，能运行的代码和好的代码之间，有很大的差别。从编写功能到编写软件，关键在于学会写出不仅能解决当前问题，还能长期使用的代码。

经过多年编写、检查和维护软件，我注意到一些区别业余代码和专业代码的模式。下面是一些我希望在职业生涯早期就有人告诉我的经验。

代码是写给人看的

首先要明白，代码主要是写给人看的，其次才是给机器运行。编译器不在乎你起的变量名，但半夜两点调试你代码的程序员一定在乎。

让代码自己讲故事

好的代码应该像好文章一样容易理解。使用足够清晰的命名，这样就不需要太多注释来解释代码在做什么。

看看下面的例子：

修改前：

def calc(c, p):
    # 计算总价
    total = 0
    for id in p:
        total += db.get_price(id)
    return total

修改后：

def calculate_order_total_for_customer(customer: Customer, product_ids: list[int]) -> float:
    total_price = 0.0
    for product_id in product_ids:
        total_price += db.get_price_for_product(product_id)
    return total_price

第二个版本自己就讲清楚了故事。新团队成员不用查文档或问别人，就能理解业务逻辑。

注释要解释原因，而不是重复代码

既然代码本身已经说明了它在做什么，注释就应该用来解释为什么这样写：

def is_user_eligible_for_discount(user: User) -> bool:
    # 市场部决定：旧版VIP身份（2021年前系统）
    # 不符合新版白金折扣计划资格
    if user.is_legacy_vip:
        return False

    return user.membership_level >= PLATINUM

这个注释记录了业务背景，否则这些信息很容易丢失。

清晰比巧妙更重要

不要为了展示聪明而写那些需要高深知识才能理解的一行代码。你未来的自己会感谢你这个决定：

修改前：

def is_valid(id_val: int) -> bool:
    return bin(id_val & 0x7FFF).count('1') % 2 == (id_val & 0x8000) >> 15

修改后：

def is_id_valid(id_val: int) -> bool:
    """验证ID的奇偶校验位"""
    VALUE_MASK = 0x7FFF
    PARITY_MASK = 0x8000

    value_bits = id_val & VALUE_MASK
    encoded_parity = (id_val & PARITY_MASK) >> 15
    calculated_parity = bin(value_bits).count('1') % 2

    return calculated_parity == encoded_parity

构建可靠的系统

代码能运行还不够，专业软件必须能妥善处理各种意外情况。

错误不是特殊情况

在生产系统中，错误是不可避免的。网络调用会失败，文件会丢失，用户会输入意外内容。设计错误处理要像设计正常流程一样仔细：

有问题的做法：

def get_user_age(user_id: int) -> int:
    age = db.query_age(user_id)
    return age if age is not None else -1  # 使用魔法值！

更好的做法：

class UserNotFoundError(Exception):
    pass

def get_user_age(user_id: int) -> int:
    age = db.query_age(user_id)
    if age is None:
        raise UserNotFoundError(f"用户 {user_id} 不存在")
    return age

第二种方法强制调用者明确处理错误情况，避免了难以调试的静默失败。

不变的数据更安全

可变状态是许多难以复现bug的根源。当数据可能意外改变时，理解程序行为就变得困难得多：

from dataclasses import dataclass, replace

@dataclass(frozen=True)  # 不可变！
class UserSettings:
    theme: str
    notifications_enabled: bool

def create_preview_settings(base_settings: UserSettings) -> UserSettings:
    # 创建新对象而不是修改原对象
    return replace(base_settings, theme="dark_preview")

使用不可变对象可以消除整类bug，让并发编程更安全。

为未来做设计

今天写的代码会在未来多年被修改、扩展和调试。要考虑到变化来组织代码。

依赖注入让代码更灵活

不要硬编码依赖，而是把它们作为参数接收。这样代码既容易测试，也容易适应变化：

不灵活的做法：

class ReportService:
    def __init__(self):
        self._generator = CsvReportGenerator()  # 永远只能用CSV

    def create_report(self, data):
        return self._generator.generate(data)

灵活的做法：

class ReportService:
    def __init__(self, generator: ReportGenerator):
        self._generator = generator

    def create_report(self, data):
        return self._generator.generate(data)

现在你可以轻松切换到JSON报告，注入假的生成器进行测试，或者同时支持多种格式。

组合优于继承

继承感觉很自然，它反映了我们对现实世界的分类方式。但在软件中，组合通常更灵活：

继承方式：

class ElectricCar(Car):
    def charge(self): ...
    def drive(self): ...

组合方式：

class Vehicle:
    def __init__(self, engine: Engine, fuel_system: FuelSystem):
        self._engine = engine
        self._fuel_system = fuel_system

    def start(self):
        self._engine.start()

    def refuel(self):
        self._fuel_system.refuel()

使用组合，你可以轻松创建混合动力车辆、电动摩托车或氢燃料汽车，而不需要重构整个类层次结构。

测试是预测未来的利器

测试不只是为了发现bug，更是为了预测代码在不同条件下的行为。

测试行为，而不是实现

关注测试代码完成了什么，而不是它怎么完成的：

关注实现的测试（脆弱）：

def test_user_service_calls_database():
    service.create_user(user_data)
    mock_db.insert.assert_called_once()  # 测试内部机制

关注行为的测试（健壮）：

def test_creating_user_makes_them_findable():
    user_id = service.create_user(user_data)
    found_user = service.get_user(user_id)
    assert found_user.email == user_data["email"]  # 测试最终结果

第二个测试在重构后仍然有效，因为它关注的是核心行为。

尽量使用真实对象

模拟对象和桩对象有其用处，但实现真实行为的假对象能让测试更有信心：

class InMemoryUserRepository:
    def __init__(self):
        self._users = {}
        self._next_id = 1

    def save(self, user: User) -> int:
        user_id = self._next_id
        self._next_id += 1
        self._users[user_id] = user
        return user_id

    def find(self, user_id: int) -> User:
        return self._users.get(user_id)

这个假仓库的行为像真的一样，但不需要数据库，让你的测试既快速又可靠。

思维方式的转变

这些原则代表了一种根本的思维转变。不要只问"我怎么能让这个工作？"，开始问：

"别人怎么理解这段代码？"
"失败时会发生什么？"
"未来这个需要怎么改变？"
"我怎么验证这个是正确的？"

专业软件开发是一种共情能力的体现，对你未来的自己、你的团队成员、依赖你代码的用户都要有共情。你写的每一行代码都是为他人考虑的小小举动。

能运行的代码和专业软件之间的区别，不在于知道更多高级技术或框架，而在于培养写出既能满足当前需求、又能适应未来变化的代码的纪律性。当你开始这样思考时，你会发现好代码不仅更容易维护，实际上在一开始写起来也更容易。

在代码质量上的投入，会在软件运行的每一天带来回报。从今天开始建立这种投入吧。

本文内容仅供个人学习/研究/参考使用，不构成任何决策建议或专业指导。分享/转载时请标明原文来源，同时请勿将内容用于商业售卖、虚假宣传等非学习用途哦～感谢您的理解与支持！

链接: https://fly63.com/article/detial/13123