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
2026-06-30
CI/CD 方法论的前世今生
软件工程有一条反直觉的规律：集成的频率越高，每次集成的痛苦越小。这条规律从 1990 年代末被 Kent Beck 写进极限编程的实践清单，到今天演化出一整套涵盖构建、测试、部署、发布的自动化体系。CI/CD 不是某一个工具或某一种流程，而是三十年工程实践反复迭代的产物。 持续集成的诞生（1996-2006） 极限编程与 CI 的起源 1996 年，Kent Beck 加入克莱斯勒公司的 C3（Chrysler Comprehensive Compensation System）项目。这个项目此前陷入僵局，Beck 将它作为极限编程（XP）的试验田，引入了十二条核心实践，持续集成是其中之一。CI 的核心主张很简单：开发者每天多次将代码集成到主干，每次集成都触发自动构建和测试。1999 年出版的《Extreme Programming Explained: Embrace Change》正式将 CI 确立为一个命名实践。 CI 要解决的问题在当时有一个形象的说法叫"集成地狱"（integration hell）——团队各自开发数周甚至数月，最后合并代码时发现冲突...
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：当任务活得比会话长 持久...
2026-02-07
API 兼容性设计
在软件工程中，API 兼容性是一个至关重要但又经常被忽视的问题。良好的兼容性设计能够确保系统的平滑演进，避免因 API 变更导致的客户端崩溃和服务中断。本文将从多个维度探讨 API 兼容性设计的最佳实践。 什么是 API 兼容性 API 兼容性分为两种类型： 向前兼容：旧版本的客户端能够与新版本的服务端正常通信。即服务端升级后，旧客户端仍能正常工作。 向后兼容：新版本的客户端能够与旧版本的服务端正常通信。即客户端升级后，旧服务端仍能提供服务。 在实际项目中，我们通常更关注向前兼容，因为服务端的升级往往不可控，而客户端的更新节奏各异。 破坏性变更的分类 破坏性变更是指会导致现有客户端无法正常工作的 API 变更。主要分为三类： 1. 接口签名变更 123456789// 变更前public interface UserService { User getUser(String userId);}// 变更后 - 破坏性变更public interface UserService { User getUser(String userId,...
2018-10-26
checklist
写代码 checklist 注意位置 注意顺序 注意初始化 注意返回值 注意注释 注意防御性编程 注意数据库性能 上线 checklist 代码变更 check 代码 配置变更 check 配置 系统变更注意上线顺序 依赖中间件变更注意配置中间件 配置中心配了吗 交互所有细节都实现了吗？ 配监控和埋点 数据库变更了吗？ 安全检查
2026-02-07
变更日志（Changelog）规范
什么是变更日志 变更日志（Changelog）是一个按时间顺序记录项目所有重要变更的文件。它帮助用户、开发者和利益相关者了解每个版本中发生了什么变化，包括新功能、Bug 修复、破坏性变更等。 为什么需要变更日志 用户友好：让用户快速了解新功能、修复的问题和需要注意的变更 版本追溯：帮助定位问题首次出现或修复的版本 团队协作：统一团队对变更的理解和沟通 发布管理：辅助版本发布流程和发布说明的撰写 与 Git Log 的区别 特性 变更日志 Git Log 目标受众 用户、开发者、利益相关者 开发者 内容粒度 功能级别的高级描述 每次提交的详细记录 可读性 高度结构化、易于阅读 技术性强、包含实现细节 维护方式 手动维护或自动化生成 自动记录所有提交 版本关联 按版本组织 按时间顺序 Git Log 记录所有的代码提交，包括内部重构、测试调整等；而变更日志只记录对用户有意义的变更。 Keep a Changelog 规范 Keep a Changelog 是目前最广泛采用的变更日志规范，由 Olivier Lacan 创建。 变更类型分类 Ke...
2026-03-27
Harness Engineering 完整指南：从 Prompt Engineering 到实践落地的三级跃迁
2020 年我们学会了跟模型说话（Prompt Engineering），2025 年我们学会了给模型喂信息（Context Engineering），2026 年我们学会了给模型搭脚手架（Harness Engineering）。这三个 Engineering 不是并列关系，而是严格的超集关系：PE ⊂ CE ⊂ HE。本文从"为什么上一个不够"的视角，系统梳理这条演进路径上的每一次范式跃迁，并给出从 Anthropic 实证到工程落地的完整方案。 一个类比秒懂三级跃迁 在讲技术之前，先用一个所有人都能理解的类比。 想象你要指挥一个完全失忆的天才厨师做一桌满汉全席： Prompt Engineering 就是学会怎么跟厨师下达指令。你发现说"做道好吃的"不行，得说"用中火煎三分钟，翻面后加酱油 15 毫升"。这是措辞的艺术。 Context Engineering 就是学会怎么给厨师备料。光会下指令不够——厨师面前得摆好食材、调料、菜谱、食客的过敏信息。你要设计一个动态备料系统，让厨师在需要的时候拿到需要的东西...
