pythia-comment

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Comments - one line, or somewhere else

注释 —— 一行,或放到别处

Announce at start: "Using pythia-comment — one line, date - author - what changed."
Phase: Do — it applies while writing, before
pythia apply
sees the file
A 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 join
date - author - what changed
, with the date as
DD/MM/YYYY
. The author is the developer's handle, never the agent's: the agent did not decide this, and a blame trail that names a tool is a dead end.
--
for PL/SQL and SQL. That is the whole surface this skill covers — what pythia applies.
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/YYYY
。作者是 开发者的标识,绝不是 Agent 的:这个决定不是 Agent 做的, 而一条指向工具的 blame 记录是一条死胡同。
PL/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 writeWhere it goes
why this shape, and what breaks without itthe header block of the .sql deliverable
a rule that must not regressa test or verifier, as an assertion with a message
the decision, and the alternatives you rejectedthe spec, or the ticket
what changed and why, for a reader of historythe commit message
what the statement doesnowhere — 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 :marker
The 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 上次写入之后被移动时,它会触发。