pythia-comment
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseComments - one line, or somewhere else
注释 —— 一行,或放到别处
Announce at start: "Using pythia-comment — one line, date - author - what changed."
Phase: Do — it applies while writing, before sees the file
pythia applyA comment is the only part of a change no compiler checks and no test covers,
so it is the part that rots. One line survives the next rewrite. A paragraph
becomes a claim the next reader has to disprove before they can work.
开始时声明: “正在使用 pythia-comment —— 一行,日期 - 作者 - 改了什么。”
阶段: 执行 —— 在编写时适用,在 看到文件之前
pythia apply注释是变更中唯一没有编译器检查、也没有测试覆盖的部分,
所以它是最容易腐烂的部分。一行注释能在下一次重写中存活。
一段注释则会变成下一个读者必须先推翻才能继续工作的一个声明。
The shape
格式
sql
-- 11/09/2026 - jdoe - source flag reads the mapping table, not the joindate - author - what changedDD/MM/YYYY--ASCII only. Parts of the chain around a .sql file still read it as ANSI,
and a diacritic there becomes mojibake in something the database keeps
forever. Vietnamese without diacritics is a house style for exactly this
reason, and it is a fine one.
sql
-- 11/09/2026 - jdoe - source flag reads the mapping table, not the join日期 - 作者 - 改了什么DD/MM/YYYYPL/SQL 和 SQL 使用 。这就是这个 skill 覆盖的全部表面 —— 也就是 pythia 应用的内容。
--仅 ASCII。 .sql 文件周围的一些环节仍然以 ANSI 方式读取内容,
其中的变音符号会在数据库永久保存的内容中变成乱码。
不带变音符号的越南语正因为这个原因成为一种团队风格,
而且它是个不错的风格。
One line
一行
If it needs a second line, the comment is the wrong container. Move it:
| What you were about to write | Where it goes |
|---|---|
| why this shape, and what breaks without it | the header block of the .sql deliverable |
| a rule that must not regress | a test or verifier, as an assertion with a message |
| the decision, and the alternatives you rejected | the spec, or the ticket |
| what changed and why, for a reader of history | the commit message |
| what the statement does | nowhere — the statement already says it |
Comment only what the code cannot show: a trap, a decision, a why.
如果需要第二行,那这个注释用错了容器。把它移走:
| 你本来要写的内容 | 应该放到哪里 |
|---|---|
| 为什么是这个形状,缺了它会破坏什么 | .sql 交付文件的头部说明块 |
| 一条不能回退的规则 | 测试或验证器,作为带消息的断言 |
| 这个决定,以及你否定的备选方案 | 规格说明,或 ticket |
| 改了什么以及为什么,给阅读历史的人 | 提交消息 |
| 语句是做什么的 | 哪里都不放 —— 语句本身已经说明了 |
只注释代码无法展示的内容:陷阱、决定、原因。
Do not
不要
- Multi-line explanatory blocks above one statement.
- Banners, box drawing, .
-- ==== section ==== - Bullet lists, quoted error codes, revision archaeology inline.
- Commented-out code kept as documentation. Delete it — the journal and the VCS both remember, and neither of them lies about what is live.
- Touching comments on code you are not changing. That is a different diff, and it buries yours.
- 在单条语句上方写多行解释性注释块。
- 横幅、方框线、。
-- ==== section ==== - 项目符号列表、引用的错误码、内联的修订考古。
- 把注释掉的代码当作文档保留。删掉它 —— 日志和版本控制系统都记得, 而且它们都不会对哪些是活代码撒谎。
- 触碰你没有修改的代码上的注释。那是另一份 diff, 并且会埋没你的变更。
Before you finish
完成之前
Count the comment lines you added. More than one per statement is a rewrite,
not a trim.
Then confirm the comment actually reached the database. A comment is exactly
the kind of line a second writer drops without noticing, and it costs nothing
to check:
sql
select count(*) from all_source
where owner = :owner and name = :name and text like :markerThe preview's changed outside pythia warning is the other half of that
check — it fires when the object moved since pythia last wrote it.
数一下你添加的注释行。每条语句超过一行就是重写,
而不是精简。
然后确认注释确实到达了数据库。注释恰恰是那种
会被第二个写手悄悄丢掉的行,而且检查它不需要任何成本:
sql
select count(*) from all_source
where owner = :owner and name = :name and text like :marker预览中的 changed outside pythia 警告是检查的另一半 ——
当对象自 pythia 上次写入之后被移动时,它会触发。