工程師的
程式碼片段備忘錄管理
本頁面由日文原文機器翻譯而成。 閱讀日文原文
工程師的程式碼片段備忘錄管理是指在日常開發中發現的有用的程式碼片段、解決方案、設計模式透過備忘錄應用程式立即捕獲，以可搜尋的形式積累的管理方法。 記下調查過一次的事情，就不用重新進行同樣的搜尋了。 本報道將解說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錯誤的解決方法，用郵件發給你”一說，共享就完成了。
相關報道
