What is the best comment in source code you have ever encountered? [closed]
What is the best comment in source code you have ever encountered? [closed]
All articles on this blog are licensed under CC BY-NC-SA 4.0 unless otherwise stated.
Related Articles
2018-10-26
checklist
写代码 checklist 注意位置 注意顺序 注意初始化 注意返回值 注意注释 注意防御性编程 注意数据库性能 上线 checklist 代码变更 check 代码 配置变更 check 配置 系统变更注意上线顺序 依赖中间件变更注意配置中间件 配置中心配了吗 交互所有细节都实现了吗？ 配监控和埋点 数据库变更了吗？ 安全检查
2026-06-14
Loop Engineering：从 Boris 的 /loops 到持久 Agent 工程
本文的 Loop Engineering 取工程视角：持久 Agent 自动化的工程抽象，包括定时触发、长期运行、多会话并发、可恢复状态、权限边界、验证证据和人工升级路径。Claude 官方在 Getting Started with loops 里给出的 4 种循环分类（Turn-based / Goal-based / Time-based / Proactive）是操作视角的互补坐标系，见后文「循环的 4 种触发形态」。 本文与已有文章的边界 本博客已有 Agent Loop、Ralph Loop、Goal、Harness Engineering、Hook 体系等相邻文章，本文专门讨论 Loop Engineering。和已有文章的边界： 已有文章 主要讨论 与本文的关系 AI Coding Agent 的 Hook、Loop 与插件体系 Codex、Claude Code、OpenCode、OMC 的运行时结构 写到 loop 与 hook，但没有以 /loops 和 Routines 的持久自动化为主线 持久 Agent：当任务活得比会话长 持久...
2019-02-13
所谓解耦
软件设计，必有单元/片段，不管他们叫做系统、层次、模块、类型和方法，都是为了在一个抽象颗粒度上分割复杂度，让我们降低思考的难度，并且进行团队协作。 我们在进行系统交互的时候，要尽量设计单元交叉点通过薄的中间层交互。也就是放弃直接性，拥抱间接性。 间接性的实现，就是契约、接口或者门面/桥接模式。这些实践的使用，可以轻易让我们切换层次之间的实现，而使变动不扩散出去。
2018-10-08
系分方法论交流笔记
分析、设计和架构的区别 系分 = 业务分析 + 系统设计 系分其实就是 Analysis + Design 业务分析才是最重要的大头 要理解： 架构约束 项目约束 要有： 权衡 选择 的过程 理解业务，要理解业务背后的东西，产出的是模型。 一步一步走，推演出来解决方案，要有方法论。 系统设计是很明确的工作了 应用设计 + 数据设计 + 技术设计 = 系统方案 要考虑的额外问题： 非功能设计：运行关注点、运维关注点、开发关注点、测试关注点。 项目约束 常见方法论 用例驱动设计 SOAD 面向服务的分析和设计 OOAD 面向对象分析和设计 DDD 领域驱动设计 DDD特别适合复杂系统。有一个以不变应万变的对象，才可以在未来承载复杂的业务演进过程。 这几种方法论可以混合使用。 需求分析与业务建模 把 prd 从薄读到厚，把文档中缺失的部分补全。 系分做 PRD 评审的时候，影响比较大的点一定要尽早确认。一些对系统变化可控，可预测的变化，可以暂时放过，后续在补充。 面向服务的业务建模 分析主业务服务，设计业务功能域，设计业务功能域边界。这个过程可能不断地螺旋式地重构。 如果用...
2026-03-18
在智能体优先的世界中利用 Codex
原文作者：Ryan Lopopolo，OpenAI 技术人员。本文记录了 OpenAI 内部一个工程团队历时五个月、以"零人工编码"方式构建并交付真实软件产品的完整经验。 在过去五个月里，我们的团队一直在进行一项实验：构建并交付一款软件产品的内部 beta 版，其中没有一行代码是人工编写的。 该产品有内部日常活跃用户和外部 Alpha 测试者。它经历了交付、部署、故障和修复的整个过程。与众不同的是，每一行代码 — 从应用逻辑、测试、CI 配置、文档、可观察性到内部工具 — 全都是由 Codex 编写的。据估计，我们只用了手工编写代码所需的大约 1/10 的时间就完成了这项工作。 人类掌舵。智能体执行。 我们有意选择这一限制，以便构建必要的内容，从而将工程速度提升数个数量级。我们用了几周的时间来交付最终达到一百万行代码的项目。为此，我们需要了解，当软件工程团队的主要工作不再是编写代码，而是设计环境、明确意图和构建反馈回路，从而使 Codex 智能体能够可靠地工作时，会发生哪些变化。 这篇文章要说的是，在我们与智能体团队一起从零开始打造一款全新产品的过程中，所...
2026-02-07
变更日志（Changelog）规范
什么是变更日志 变更日志（Changelog）是一个按时间顺序记录项目所有重要变更的文件。它帮助用户、开发者和利益相关者了解每个版本中发生了什么变化，包括新功能、Bug 修复、破坏性变更等。 为什么需要变更日志 用户友好：让用户快速了解新功能、修复的问题和需要注意的变更 版本追溯：帮助定位问题首次出现或修复的版本 团队协作：统一团队对变更的理解和沟通 发布管理：辅助版本发布流程和发布说明的撰写 与 Git Log 的区别 特性 变更日志 Git Log 目标受众 用户、开发者、利益相关者 开发者 内容粒度 功能级别的高级描述 每次提交的详细记录 可读性 高度结构化、易于阅读 技术性强、包含实现细节 维护方式 手动维护或自动化生成 自动记录所有提交 版本关联 按版本组织 按时间顺序 Git Log 记录所有的代码提交，包括内部重构、测试调整等；而变更日志只记录对用户有意义的变更。 Keep a Changelog 规范 Keep a Changelog 是目前最广泛采用的变更日志规范，由 Olivier Lacan 创建。 变更类型分类 Ke...
