writing-beautiful-code

name: writing-beautiful-code description: 当写代码前、给技术方案前，或讨论、审查、重构代码审美、代码是否干净、是否丑、是否优雅、是否简单优先、是否简单第一、代码/组件/函数/文件/模块该不该拆分、拆分价值与损失、是否过度防卫、是否过度抽象、是否像补丁堆叠，或用户明确要求提升代码审美、写出美丽代码时使用。

Writing Beautiful Code

规则列表

• universal-only：只沉淀任何项目都适用的通用代码审美原则；项目、框架、目录、工具链、命名体系或业务架构专属规则不进入这里。
• less-but-sharp：规则宁缺毋滥，必须简练，但要明确到能指导下一次判断。
• named-list-rules：规则用 Markdown 列表维护；每条规则必须有稳定英文 slug，不使用编号。
• visible-main-flow：美丽代码让真实业务流程直接可见，不靠一串小私有函数制造“做了很多事”的假象。
• boundary-only-defense：防御、兼容、解析和归一化只放在真实边界；内部协作者之间依赖明确 contract。
• catch-at-real-boundaries：只在真实错误边界捕获异常，例如请求入口、后台任务调度器、事件 listener 调用者或进程边界；不要给每个内部函数调用都补 try/catch 或 .catch(...)。脱离调用栈的异步任务也应由一个 owner 级错误归口承接，而不是在业务流程中散落 catch。
• no-alias-ladders：不要为一个新 contract 同时读取多套历史字段名、别名或猜测路径。兼容旧输入时，只能在真实迁移/适配边界做一次显式归一化，并写清删除条件；内部业务代码只读规范字段。
• types-tell-truth：类型应该表达事实，不用 as 把未知结构伪装成确定合同。
• semantic-responsibility-names：文件、class、函数和字段命名应语义化、无歧义、清晰简洁，并让读者能从名称识别其主要职责。
• defaults-have-owners：默认值必须属于拥有该策略的 owner，并在主流程或策略 owner 里显式出现。 Reader、parser、getter、helper 只能读取事实，不能把缺失值偷偷改成默认策略。
• single-fact-owner：一个事实只应有一个清晰 owner；不要用双写状态、重复缓存或多条并行链路表达同一件事。
• simplest-shape-first：先用能工作的最少概念、最少 owner、最少文件表达主流程；只有当局部逻辑已经出现真实重复、不变量、生命周期或稳定变化点时，才升级成新抽象。
• abstraction-necessity-check：新增任何抽象前，必须先问它是否必要，并同时写清它带来的好处和损失。好处不足以抵消新增名字、文件、跳转、参数合同和心智负担时，不新增。
• abstractions-pay-rent：抽象只有在减少真实复杂度、表达稳定语义或隔离真实变化点时才成立。
• split-pays-for-itself：拆分代码、组件、函数、文件或模块时，收益必须大于新增的名字、跳转、参数合同和心智负担。
  • 拆分的价值：让主流程更可见，隔离稳定变化点，消除真实重复，保护不变量，形成可复用且语义清晰的边界，或让测试与维护明显更直接。
  • 拆分的损失：新增命名和文件跳转，制造 props/参数搬运，让局部上下文分散，把自然内聚流程切碎，或产生只有一两个透传方法的空心抽象。
  • 如果拆分只是把局部逻辑从 A 搬到 B，并新增一串字段传递、handler 转发或阅读跳转，就不要拆。
  • 当代码职责局部闭合、主流程短、变化原因一致且没有真实复用压力时，保持内聚通常比提前抽象更美。
• split-by-change-reason：拆分依据是变化原因、生命周期、不变量和复用边界，不是行数、JSX 存在、函数数量或“看起来更分层”。
  • 同一段代码出现多个独立变化原因、稳定重复结构、独立生命周期或明确 owner 边界时，应拆。
  • 只是为了理论洁癖、目录对称、命名好看或让每个文件更短而拆，通常是在增加复杂度。
• stable-object-shape：对象构造应直接呈现合同形状；不要用条件 spread 拼可选字段来隐藏对象形态变化。
  • 常规业务对象优先显式赋值为 undefined / null 或先建清晰局部值。
  • 字段值本身可以用清晰的三元表达式表达 undefined / null；问题是条件 spread 让对象形态变化藏进展开语法里。
• prefer-const：优先用 const 表达派生值；只有真实需要重新赋值的流程状态才用 let。若 let 只是为了跨分支拼结果，优先考虑用清晰表达式或有稳定语义的 helper 返回值。

使用方式

• 讨论代码时先指出“丑”的结构性来源，而不是只挑语法细节。
• 输出结论时给出明确取舍：保留什么、删除什么、归谁负责，以及为什么这样更美。