6 posts
Literate programming 承诺单一事实来源，但手动的 weave 和 tangle 步骤会破坏 CI/CD 流水线。以下是如何自动化提取和文档生成，使 Markdown 文件保持规范。
如果你的构建流水线必须等你打开终端输入 才能运行，那你就没有文学化程序。你有的只是一本绑着编译器的日记。 文学化编程的全部意义在于散文和代码共享单一事实来源。Markdown 文件就是产物。其他一切——可执行源码、渲染后的文档、测试文件——都是派生的。派生产物属于 CI，不属于你的工作记忆。 问题不是 CI 能不能…
我花了30天时间，在向LLM索要代码之前先撰写设计说明。结果改变了我对rubber-ducking的看法。
大多数开发者把LLM用反了。我们用五个词描述需求，拿回200行代码，然后花下一个小时调试模型做出的假设。 我花了三个月时间运行相反的流程：在索要哪怕一行代码之前，先写一份完整的设计说明。结果代码缺陷更少了，但真正的进步在于我自己的理解。 Donald Knuth在1984年提出了"literate…
Literate programming 将 Markdown 文件作为单一事实来源，使文档、测试和实现保持同步。以下是如何用三十行 Python 实现它。
你的文档、测试和代码是三份文件，讲着同一个故事，却讲得都很糟糕。 你在源码里更新了函数签名，忘了改 README 里的示例。一周后，新员工把过时的代码片段复制到了生产环境。你的测试文件仍然把旧的行为编码为预期结果。现在你有两个 bug 和一个文档工单。…
LLM 对话包含意图、被拒绝的替代方案以及可运行的代码。这正是文档应该包含的内容。以下是将 ephemeral chat 转换为持久、可搜索的文档，同时不丢失叙事的方法。
你花了 45 分钟和 Claude 设计一个 retry circuit。你解释了 failure modes，因为 exponential backoff 会掩盖 cascading pressure 而拒绝了它，确定了 token-bucket rate limiting with…
每个编译器都将你的代码视为树，但你的编辑器让你编辑原始文本。以下是结构化编辑的实际样子、为什么它没有占领市场，以及如何在不更换工具的情况下借用其优势。
每种编程语言都有形式语法。编译器读取它，构建解析树，拒绝任何不符合的内容。编辑器完全无视语法，让你想输入什么就输入什么。 这种脱节是大量摩擦的惊人来源。自动补全建议的标识符在上下文中毫无意义。语法高亮在重构中途崩溃。编辑器眼睁睁看着你犯错，然后报出「Unexpected…
Literate programming承诺代码应该首先为人类编写，其次才是为机器。四十年后，几乎没有人这样写。以下是软件文档化中最优雅的理念为何未能改变我们工作方式的原因。
1984年，Donald Knuth发表了一篇提出根本性反转的论文。程序不应该是为编译器编写、为人类添加注释的。它们应该被写作为人类的文学作品，编译器从中提取可执行部分。他称之为literate programming，并以这种方式构建了TeX。 这个想法很美。它在现代软件开发中也几乎完全缺席。…