工程师的
代码片段备忘录管理
本页面由日语原文机器翻译而成。 阅读日语原文
工程师的代码片段备忘录管理是指在日常开发中发现的有用的代码片段、解决方案、设计模式通过备忘录应用程序立即捕获，以可搜索的形式积累的管理方法。 记下调查过一次的事情，就不用重新进行同样的搜索了。 本报道将解说4的管理方法。
彻底解说工程师的代码片段备忘录管理。 介绍通过即时备忘录捕获、标签分类、搜索优化、团队共享的4几种方法大幅提高开发效率的方法。
方法1：即时捕捉 - 想到的瞬间保存
工程师觉得“这很方便”的瞬间在开发中突然到来：
- 代码审查中：发现前辈优雅的写法
- 调试中：3发现了苦恼的bug解决方案
- 文档阅读中：发现API隐藏的便利参数
- 学习会/会议：登台者的代码例子成为参考
这些一想到“以后再总结吧”，很容易在没有记录的情况下忘记。 用Captio式发邮件给自己的话，即使在移动中也能从智能手机上立即捕捉。
方法2：基于标签的分类系统
代码片段的分类在“语言”和“类别”的2轴上进行：
- 语言标签：[Python] [JavaScript] [TypeScript] [SQL] [Shell] [Go]
- 类别标签：[API] [DB] [UI] [Auth] [Deploy] [Test] [Performance]
- 状态：[已验证][未验证][不推荐]
统一在备忘录的开头贴上标签的规则。 在Gmail搜索中输入“[Python][API]”，就可以立即列出与Python相关的API处理代码。
方法3：搜索优化备忘录的写法
备忘录的价值不是在“写的时候”而是在“搜索的时候”发生。 通过以下规则最大化搜索点击率：
- 包含问题文：“出现CORS错误时的应对方法”
- 错误信息原文：“Access-Control-Allow-Origin missing”
- 解决方案的总结：“在服务器端添加标题”
- 代码片段：粘贴实际移动的代码
- 参考URL：官方文档和Stack Overflow的链接
“3个月后的自己遇到同样的问题时，用什么关键词搜索？” 想象着写是诀窍。
方法4：团队共享知识库化
个人积累的片段备忘录，成为团队知识库的种子：
- 每周1共享：将那一周最有用的片段在1个Slack上投稿
- GitHub Gist化：将已验证的片段汇总到Gist中添加到README
- Notion/Wiki转写：将项目固有的知识提升为官方文档
- 入职资料：为新成员整理“常见问题和解决方法”
1人的备忘录节省了10人的开发时间。 用Captio式即时捕获→用Gmail积累→用GitHub Gist共享的3步骤是最强的。
常见问题
管理代码片段的最佳工具是什么？
即时捕捉Captio式，整理GitHub Gist・Notion・Obsidian，日常使用VS Code片段功能最合适。
片段的分类方法是什么？
用语言×类别的2轴标签进行分类。[ 像Python][API]一样统一前缀的话，搜索性会大幅度提高。
记下Stack Overflow的回答的意义是什么？
省去了重新找到答案的麻烦。 以适用于自己项目的形式保存吧。
不同语言的片段备忘录的最佳做法
Python片段用“库名+处理内容”记下的话，搜索性会最大化。 Python的库很丰富，区分标准库和第三方库以后会有所帮助。
- 命名规则：[Python][pandas] 读取CSV处理缺失值 — 必须将“库名”包含在标签中
- 版本信息：Python 3.11以后可以使用的新语法（match-case语句等）要注明版本。“[ 添加Python3.11+]”这样的标签
- 虚拟环境命令：venv、conda、poetry等环境构建命令虽然经常使用，但容易忘记。“[ Python][env] poetry add --dev pytest”一样的备忘录
- 单线集：列表内含记号和lambda式等，Python强大的单线在忘记的时候才需要。 和具体例子一起保存
JavaScript/TypeScript因为框架变化很大，所以“框架名称+版本”的记载特别重要。
- React/Next.js：像“[React18][Hooks]”“[Next14][App Router]”一样明确说明主要版本和范式。 Server Components相关在Pages Router和App Router上完全不同
- TypeScript的类型：复杂的泛型和实用型（Partial、Pick、Omit）的使用方法很容易忘记。 和具体的use case一起备忘录
- npm/yarn命令：软件包的安装、卸载、版本指定的命令略有不同。“[ Npm] npm install --save-exact package@1.2.3”一样的备忘录
- 浏览器API：Intersection Observer、Web Workers、Service Worker等，使用频率低，需要的时候不能马上想起API作为片段保存
SQL・外壳・基础设施系命令的“执行环境”和“危险度”的信息特别重要。
- SQL：明确了“[SQL][PostgreSQL]窗口函数排名”“[SQL][MySQL] JSON型列的查询”等RDBMS的种类。 MySQL、PostgreSQL、SQLite的语法不同的情况很多
- 外壳脚本：像“[Shell][破坏性] rm -rf的安全替代：trash-cli”一样，在实际环境中执行的危险命令加上[破坏性]标签
- Docker/K8s：像“[Docker]通过多阶段构建减少图像大小”“[K8s] Pod不重启ConfigMap更新”一样，将运用场景包含在标题中
- Git：像“[Git]只将特定的提交应用于其他分支：cherry-pick”一样，用日语写出操作的目的的话，搜索点击率会提高
通过邮件管理代码片段的优点
虽然有很多代码片段的管理工具，但在“捕获的即时性”和“搜索的便利性”的兼顾方面，基于邮件的管理有独特的优点。
优点1：捕获的麻烦少
打开GitHub Gist，输入标题并粘贴代码...... 这样的流程，在移动中或会议中不能使用。 作为iOS工程师，我每天通过邮件积累Swift的片段，半年内200以上的片段自然而然地被图书馆化了。 Captio式的话，在智能手机上只要3秒就可以记下代码片段和上下文。“ 与其想着“等会整理在Gist上”而忘记，不如先把它扔进邮件里比较确定。
优点2：Gmail的搜索性能
Gmail的搜索功能非常高性能。“ 像“from:noreply@mail.simplememofast.com python api retry”一样，用发送源+关键词搜索的话，可以精确地缩小自己的片段笔记。 全文搜索是理所当然的，也可以根据附件名称和日期范围进行筛选。
优点3：不依赖工具
更换片段管理工具非常麻烦。 导出→导入的兼容性问题，标签和元数据的消失等。 然而，邮件是使用了几十年的标准结构，不依赖于特定的工具。 无论Gist和Notion变更规格还是服务终止，邮件中保存的片段都不会受到影响。 对Markdown基础工具感兴趣的人请看与Obsidian的差异和与Joplin的比较。
优点4：自动记录时间序列
邮件会自动记录发送日期，所以可以准确知道“这个片段是什么时候保存的”“这个bug是什么时候解决的”。 回顾项目或撰写技术博客时，作为“时间序列的知识日志”非常有用。
优点5：团队共享简单
如果想将保存的片段备忘录分享给同事的话，邮件的话直接转发就可以了。 不需要格式转换和账号邀请。“ 前几天的CORS错误的解决方法，用邮件发给你”一说，共享就完成了。
相关报道
