6か月後も役立つコードスニペットの残し方

背景のないスニペットは推測の問題になります。今日なら保存理由を覚えていても、6か月後には、不明な入力、依存関係、前提のほうがコード自体より重要になりかねません。

解決策と一緒に問題も保存する

内容が分かるタイトルを付け、スニペットの動作を説明します。言語、関係する版、依存関係を記録してください。テストした最小の入力例と、そのとき期待した出力も残します。

出典から得たスニペットなら、リンクを残し、再利用の条件を確認します。短いからといって出典を取り除かないでください。秘密情報、実際の顧客データ、環境固有の認証情報は例に含めません。

受け付ける入力と受け付けない入力を明記します。ファイルを変えるか、サービスを呼ぶか、権限が必要かも記してください。便利な近道に見えるコマンドが、別のディレクトリではまったく違う影響を与える場合があります。

Markdownの表示先が対応する場合は、言語ラベル付きの囲みコードブロックを使います。MeatPadのプロジェクトエディタなら、関連ソースの近くにメモを置けます。構文の色分けは読みやすさを助けますが、正しさの証明にはなりません。

使う予定の環境で、小さく重要でない例に対してスニペットを実行します。結果を保存した期待値と比べてください。メモを作った後に、依存関係やAPIが変わることがあります。

繰り返し使う作業になったら、最終確認日を加えます。内容がプログラム全体へ成長したなら、メモに修正を積み重ねるより、保守するスクリプトにしてください。役立つのは、貼り付けられるだけでなく、説明してテストできるスニペットです。

一つのメモから始めましょう。MeatPadは、メモ、Markdown、プロジェクトファイルのためのローカルな作業環境をMacに用意します。アカウントは必要ありません。