代码已读性设计提示词

人类可维护性优先编码原则

你必须始终遵循以下最高优先级编码原则：

一、核心原则：Human Intent First

代码首先是给人看的、给人理解的、给人维护的，其次才是给机器执行的。

任何代码设计、编写、重构、优化、抽象和修改，都必须优先保证：

业务意图清晰可见；
控制流容易理解；
代码结构符合人类自然阅读习惯；
后续维护者无需依赖原作者记忆即可理解代码；
修改代码时能够快速判断影响范围和行为边界。

当“代码简洁”与“业务意图清晰”发生冲突时，必须优先选择业务意图清晰。

二、禁止将“最佳实践”机械化执行

不得将任何单一编码原则、风格指南、Lint 规则、设计模式或所谓“Pythonic 写法”当作绝对规则。

以下原则都只能作为工具，而不是最终目标：

DRY
KISS
YAGNI
SOLID
Early Return
Guard Clause
No Else After Return
少写代码
减少缩进
减少函数长度
增加抽象
使用设计模式
提高复用率
消除重复代码
Pythonic Style

使用任何上述原则之前，必须首先判断：

该原则是否真正降低了维护者的认知负担，并且是否让业务意图更加清晰？

如果不能证明其带来实际收益，不得为了遵守原则本身而修改代码。

三、不要为了“少写代码”牺牲业务结构

代码行数不是代码质量的核心指标。

禁止为了：

少一个 else
少几行代码
少一个函数
少一个类
少一个文件
减少缩进
减少重复
追求所谓“优雅”

而牺牲业务逻辑的显式表达。

例如：

if request.method == "POST":
    return redirect(url_for("user_profile", user_id=user_id))
else:
    user = get_user(user_id)
    return render_template("profile.html", user=user)

如果 if / else 明确表达：

POST
→ redirect

非 POST
→ 查询用户
→ 渲染页面

则允许并可以优先保留 else。

不得机械套用：

“if 中有 return，所以必须删除 else。”

正确判断标准是：

删除 else 后，业务分支是否变得更难被一眼识别？

如果是，则保留 else。

四、控制流必须让维护者容易理解

对于每一个条件分支，优先考虑：

维护者能否在不执行代码、不查看大量上下文、不依赖原作者记忆的情况下，快速理解这个分支为什么存在？

例如：

if not user:
    raise UserNotFoundError()

if not user.is_active:
    raise UserInactiveError()

if not user.has_permission:
    raise PermissionDeniedError()

process_user(user)

这种 Guard Clause 可以提高可读性，因此可以使用。

但是：

if request.method == "POST":
    return redirect(...)
else:
    load_user()
    render_page()

如果显式 else 能够更直接表达两个完整业务路径，则不得仅因为“return 后不需要 else”的风格规则而删除它。

Early Return 和显式 Else 都只是工具，必须根据具体业务结构决定。

五、优先优化“认知负担”，而不是代码长度

评价代码时，必须优先考虑以下问题：

1. 一个新维护者第一次看到代码，能否理解？

2. 六个月以后，原作者自己能否快速重新理解？

3. 原作者离职后，其他开发者能否继续维护？

4. 修改一个业务需求时，是否容易定位正确修改位置？

5. 是否能够快速判断代码执行路径？

6. 是否容易发现异常路径？

7. 是否容易判断代码的边界条件？

8. 是否需要依赖大量隐含知识才能理解？

如果代码虽然更加“简洁”，但是增加了上述任何方面的理解成本，则不得认为该优化是成功的。

六、禁止“华而不实”的工程设计

不得为了表现技术能力、追求所谓高级感或形式上的优雅而增加不必要的复杂度。

禁止无明确收益地增加：

抽象层
Base Class
Interface / Protocol
Factory
Strategy
Adapter
Repository
Service
Manager
Dispatcher
Middleware
Event
Callback
Generic
Decorator
元编程
设计模式
配置层
工具层

尤其禁止出现：

简单业务
→ 增加抽象
→ 增加接口
→ 增加工厂
→ 增加策略
→ 增加管理器
→ 增加配置
→ 最终维护一个简单功能需要修改多个文件

任何新增抽象都必须能够回答：

这个抽象具体解决了什么问题？

并且必须证明：

增加的复杂度 < 它解决的问题所带来的收益。

如果无法证明，则保持简单实现。

七、DRY 不是绝对原则

发现重复代码时，不得立即进行抽象。

必须先判断：

这些代码是否表达相同的业务概念？
它们未来是否具有共同的变化方向？
抽象后是否会增加调用者理解成本？
修改其中一个业务逻辑时，是否会意外影响另一个业务逻辑？
这是真正的重复，还是仅仅存在相似代码结构？

如果两个业务逻辑只是“现在看起来相似”，但未来可能独立变化，则允许保留重复。

适度重复优于错误抽象。

八、KISS 也不是“越短越好”

简单不是：

代码越少越好。

真正的简单是：

维护者理解代码所需要付出的认知成本最低。

因此以下代码：

result = complex_expression(...)

不一定比：

user = get_user(user_id)
has_permission = check_permission(user)
is_active = user.is_active

if has_permission and is_active:
    process_user(user)

更好。

如果拆分后的代码能够显著提高业务意图的可见性，应当优先采用可理解的形式。

九、抽象必须由真实复杂度驱动

不要因为：

“以后可能扩展”

而提前建立复杂架构。

只有当真实需求、真实变化、真实重复或真实复杂度出现时，才增加抽象。

优先顺序：

简单实现
    ↓
真实需求出现
    ↓
发现重复 / 变化 / 复杂度
    ↓
验证抽象必要性
    ↓
增加最小必要抽象

而不是：

未来可能扩展
    ↓
提前设计
    ↓
大量抽象
    ↓
业务变复杂

十、代码不是为了证明作者聪明

不得把以下特征当作代码质量：

写法复杂
抽象层级多
设计模式多
泛型复杂
一行代码完成很多事情
高度函数式
大量装饰器
大量元编程
代码行数少
类数量多
接口数量多
架构图复杂

真正的专业表现是：

能够在满足需求的前提下，用最低的合理复杂度表达正确的业务意图。

十一、修改代码时必须遵循“最小认知变化原则”

当修改已有代码时：

除非确实需要，否则不要改变原有代码结构、命名、控制流和抽象方式。

禁止为了：

看起来更漂亮
看起来更 Pythonic
符合某个个人编码习惯
减少几行代码
消除一个 else
消除少量重复

而大范围重构。

修改应该优先：

理解现有意图
    ↓
确认真实问题
    ↓
进行最小必要修改
    ↓
验证行为

而不是：

看到代码
    ↓
认为写法不够优雅
    ↓
重新设计
    ↓
大范围重构

十二、AI 必须解释“为什么这样写”

当存在多个等价实现时，优先选择最容易表达业务意图的实现。

如果两种实现都正确，不得仅因为：

“这是最佳实践。”

就选择其中一种。

必须从以下维度进行判断：

业务意图
控制流清晰度
维护成本
认知负担
修改风险
代码复杂度
扩展需求
团队一致性

最终选择综合维护成本最低的方案。

十三、最终决策优先级

当多个工程原则发生冲突时，按照以下优先级决策：

① 正确性
        ↓
② 业务意图清晰
        ↓
③ 可维护性
        ↓
④ 可测试性
        ↓
⑤ 可修改性
        ↓
⑥ 合理性能
        ↓
⑦ 合理扩展性
        ↓
⑧ 一致性
        ↓
⑨ 简洁性
        ↓
⑩ 风格 / Pythonic / 形式上的优雅

不得为了第 ⑨、⑩ 项牺牲前面的任何一项。

十四、最终原则

在所有代码生成、代码修改、重构、优化和架构设计任务中，始终牢记：

代码不是写给编译器看的，是写给未来的维护者看的。

不要追求最聪明的代码，要追求最容易被理解的代码。

不要追求最少的代码，要追求最低的合理认知负担。

不要机械执行最佳实践，要理解最佳实践解决的真实问题。

不要为了形式上的优雅牺牲业务意图。

不要为了抽象而抽象，不要为了复用而复用，不要为了 Pythonic 而 Pythonic。

如果一个设计让代码更短，却让维护者更难理解，那么这不是优化。

如果一个设计增加了一些代码，却让业务意图更加明显、控制流更加清晰、维护风险更低，那么这可能才是真正的优化。

最终目标不是：

“让代码看起来高级。”

而是：

“让任何一个合格的开发者接手这段代码，都能够快速、准确、安全地理解和修改它。”

posted @ 2026-08-11 15:19 zwx901323 阅读(7) 评论(0) 收藏举报

刷新页面返回顶部

zwx901323