writing-lean

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Writing lean

精简写作

The code and its specs are the first source of truth: a reader new to the project should learn it by reading them. Writing is lean when it carries only what they cannot say.

Code first. Reach for a clearer name, a smaller function or a sharper spec before a longer explanation.
One word per idea. Use the project's term for a concept, from
```
CONTEXT.md
```
or the code, every time; a synonym reads as a second concept.
Say what to do. State the target ("one-line comments"), not the ban; a prohibition earns its place only as a hard guardrail, paired with what to do instead.
Once, where it bites. Each fact has a single source of truth, below; anywhere else, link to it.
History goes to the story. What was weighed and what was rejected belong in the issue, pull request or commit, where the discussion and the diff sit beside them and
```
git blame
```
leads back.

The deletion test is the bar for every sentence you write or touch: delete it and ask what a competent reader loses. If nothing, the code already said it, and it stays deleted.

代码及其规范是首要事实来源：刚接触项目的读者应通过阅读它们来了解项目。当写作仅承载代码和规范无法表达的内容时，就是精简的。

代码优先。 在撰写更长的解释之前，先尝试使用更清晰的命名、更小巧的函数或更明确的规范。
一个概念对应一个术语。 始终使用项目中（来自
```
CONTEXT.md
```
或代码）对某个概念的既定术语；同义词会被读者当作另一个概念。
说明该做什么。 陈述目标（如“单行注释”），而非禁令；禁令仅在作为硬性防护措施，且配套了替代方案时才有必要存在。
仅在生效处记录一次。 每个事实都有唯一的事实来源（见下文）；其他任何地方都只需链接到该来源。
历史归入过程记录。 权衡过的内容和被否决的方案应放在issue、pull request或commit中，这些地方有对应的讨论和diff，也能通过
```
git blame
```
追溯到。

删除测试是衡量你写下或修改的每一句话的标准：删掉这句话，问问一位合格的读者会损失什么。如果没有任何损失，说明代码已经表达了这个意思，那就删掉它。

Where it goes

内容放置规范

Channel	Its one job
Code	Fluent: concise function and variable names that say what it does
Code comment	A constraint, trap, citation or non-obvious why, at the line it bites
Doc comment	What the member is for, in one sentence
README	The common path: what it is, how to use it, where to go next
Repo docs	A decision or context the code cannot show
Issue	What's wanted and why, in the issue form's fields
Agent brief	The contract: behaviour, acceptance criteria, scope
Pull request	What changed and why, linked to its issue
Commit message	What changed, and why when the diff cannot show it
Review comment	One finding and its fix
Thread comment	The new fact or decision, linked to what it answers
Skill, `AGENTS.md`	How an agent does the work: the steps and the reference behind them

载体	唯一职责
代码	流畅易懂：函数和变量命名简洁，能直接说明其作用
代码注释	在生效行记录约束、陷阱、引用或非显而易见的设计原因
文档注释	用一句话说明成员的用途
README	通用路径：说明项目是什么、如何使用、接下来可以去哪里
仓库文档	记录代码无法体现的决策或背景信息
Issue	在issue表单的字段中说明需求内容及原因
Agent 任务简报	约定内容：行为规范、验收标准、范围边界
Pull request	说明变更内容及原因，并关联对应的issue
Commit message	说明变更内容，以及diff无法体现的变更原因
评审评论	每条评论说明一个问题及其修复方案
讨论线程评论	说明新的事实或决策，并链接到其回应的内容
Skill、 `AGENTS.md`	说明Agent完成工作的方式：步骤及其背后的参考依据

Links from code

代码中的链接

Cite an issue in code only when it changes how the code may be modified later: a workaround to remove when

clhbid/api#123

ships, or a constraint an open decision still holds. Otherwise

git blame

leads to the pull request and its issue.

仅当issue会影响后续代码的修改方式时，才在代码中引用它：比如等

clhbid/api#123

发布后需要移除的临时方案，或是尚未敲定的决策带来的约束。否则，通过

git blame

就能追溯到对应的pull request及其关联的issue。