Loading...

What is the best comment in source code you have ever encountered? [closed]

Created2021-12-13|Updated2026-06-07

|Word Count:13|Reading Time:1mins|Post Views:

What is the best comment in source code you have ever encountered? [closed]

Author: magicliang

Link: https://magicliang.github.io/2021/12/13/What-is-the-best-comment-in-source-code-you-have-ever-encountered-closed/

Copyright Notice: All articles on this blog are licensed under CC BY-NC-SA 4.0 unless otherwise stated.

软件工程幽默

Related Articles

系分方法论交流笔记

分析、设计和架构的区别系分 = 业务分析 + 系统设计系分其实就是 Analysis + Design 业务分析才是最重要的大头要理解：架构约束项目约束要有：权衡选择的过程理解业务，要理解业务背后的东西，产出的是模型。一步一步走，推演出来解决方案，要有方法论。系统设计是很明确的工作了应用设计 + 数据设计 + 技术设计 = 系统方案要考虑的额外问题：非功能设计：运行关注点、运维关注点、开发关注点、测试关注点。项目约束常见方法论用例驱动设计 SOAD 面向服务的分析和设计 OOAD 面向对象分析和设计 DDD 领域驱动设计 DDD特别适合复杂系统。有一个以不变应万变的对象，才可以在未来承载复杂的业务演进过程。这几种方法论可以混合使用。需求分析与业务建模把 prd 从薄读到厚，把文档中缺失的部分补全。系分做 PRD 评审的时候，影响比较大的点一定要尽早确认。一些对系统变化可控，可预测的变化，可以暂时放过，后续在补充。面向服务的业务建模分析主业务服务，设计业务功能域，设计业务功能域边界。这个过程可能不断地螺旋式地重构。如果用...

智能体记忆全景综述：从短时长时之分到向量库回归文件系统（2022-2026）

22 年以前，“LLM 应用"基本等同于"调一次 ChatComplete”。从 22 年底 ChatGPT 出来到 26 年这三年里，行业发现真正决定智能体上限的不是模型本身，而是模型周围那一圈用来承载历史、外部知识与可更新偏好的记忆系统。这篇综述沿着一条主线展开：以"信息来源"为轴的四层记忆世界观，把过去三年的代表性工作放进这四层里，并且回答一个 26 年才浮出水面的反向问题——为什么大家又在把向量数据库塞回到一个 markdown 仓库或一份 SQLite 单文件里。一、把整片版图压成三句话如果把过去三年关于智能体记忆的所有论文、产品和工程实践压成三句话，大致是这样：第一，Agent 的记忆按"信息源"切是一个稳定的四层结构：训练数据（L1）、对话内数据（L2）、会话间数据（L3）、外部世界但与本会话无关的数据（L4）。每一层的写入主体不同，分别是训练管线、当前交互、Agent 自己、世界本身。围绕"是不是要再切出第五层"在 25-26 年有一些讨论，本文的判断是：Titans / ...

环境可供性：智能的一半是取到正确数据

没有工具的模型，只能靠提示词获得额外信息。提示词工程在那个阶段几乎是唯一杠杆：把背景写清楚，把例子给够，把格式约束好，让模型在已有上下文里尽量选对路径。一旦模型拥有主动提取外部数据的能力，问题就变了。智能不再只取决于模型内部能处理多少信息，也取决于它能不能从环境里拿到正确的信息。 Prompt 是喂信息，工具是取信息 prompt-only 系统的工作方式像开卷考试，但试卷、教材和草稿纸都必须提前塞进同一个信封。用户没塞进去的信息，模型默认看不见。它可以猜，可以泛化，可以从训练数据里补常识，但无法可靠知道当前项目、当前日志、当前数据库、当前 API 文档发生了什么。工具调用改变了边界。ReAct 把 reasoning 和 acting 交织起来，让模型一边推理，一边对外部知识库或环境采取动作获取观察结果。Toolformer 进一步证明，语言模型可以学习在合适时机调用 API，并把结果纳入后续预测。SWE-agent 的核心贡献也不是“又写了一个 coding prompt”，而是强调 Agent-Computer Interface：给 agent 一个适合读文件、改...

变更日志（Changelog）规范

什么是变更日志变更日志（Changelog）是一个按时间顺序记录项目所有重要变更的文件。它帮助用户、开发者和利益相关者了解每个版本中发生了什么变化，包括新功能、Bug 修复、破坏性变更等。为什么需要变更日志用户友好：让用户快速了解新功能、修复的问题和需要注意的变更版本追溯：帮助定位问题首次出现或修复的版本团队协作：统一团队对变更的理解和沟通发布管理：辅助版本发布流程和发布说明的撰写与 Git Log 的区别特性变更日志 Git Log 目标受众用户、开发者、利益相关者开发者内容粒度功能级别的高级描述每次提交的详细记录可读性高度结构化、易于阅读技术性强、包含实现细节维护方式手动维护或自动化生成自动记录所有提交版本关联按版本组织按时间顺序 Git Log 记录所有的代码提交，包括内部重构、测试调整等；而变更日志只记录对用户有意义的变更。 Keep a Changelog 规范 Keep a Changelog 是目前最广泛采用的变更日志规范，由 Olivier Lacan 创建。变更类型分类 Ke...

第 1 章欢迎进入软件构建的世界第 2 章用隐喻来更充分地理解软件开发第 3 章三思而后行：前期准备第 4 章关键的“构建决策” 第 5 章软件构建中的设计第 6 章可以工作的类第 7 章高质量的子程序第 8 章防御式编程第 9 章伪代码编程过程第 10 章使用变量的一般事项第 11 章变量名的力量第 12 章基本数据类型第 13 章不常见的数据类型第 14 章组织直线型代码第 15 章使用条件语句第 16 章控制循环第 17 章不常见的控制结构第 18 章表驱动法第 19 章一般控制问题第 20 章软件质量概述第 21 章协同构建第 22 章开发者测试第 23 章调试第 24 章重构第 25 章代码调整策略第 26 章代码调整技术第 27 章程序规模对构建的影响第 28 章管理构建第 29 章集成第 30 章编程工具第 31 章布局与风格第 32 章自说明代码第 33 章个人性格第 34 章软件工艺的话题第 35 章何处有更多的信息

Convention over Configuration over Programming

什么是 Convention over Configuration over Programming 在软件工程中，有一条重要的设计哲学层级： Convention over Configuration over Programming 约定优于配置，配置优于编程。这条原则的核心思想是：能用约定解决的问题，就不要引入配置；能用配置解决的问题，就不要写代码。它反映了软件设计中对复杂度管理的追求——越是高层次的抽象，使用成本越低，出错概率也越小。三个层次的含义 Programming（编程）编程是最灵活但成本最高的方式。开发者需要编写具体的代码逻辑来实现功能。每一行代码都是潜在的 bug 来源，都需要测试、维护和 review。编程适合处理那些真正需要定制化逻辑的场景。 Configuration（配置）配置是介于约定和编程之间的中间层。通过外部化的配置文件（如 XML、YAML、properties 等），开发者可以在不修改代码的情况下改变程序行为。配置降低了修改成本，但引入了配置管理的复杂度——配置项越多，理解和维护系统的难度就越大。 Convention（约定） ...