なぜ「小さなメモ」を残すのか？
はじめまして！株式会社プレイドでデザインエンジニアをしている、はたゆーです。
『世界一流エンジニアの思考法』から学んだことをもとに、エンジニアが実装前や実装中に残す「小さなメモ」について考えてみました。この「小さなメモ」は、後からコードを読み解く際の助けになったり、チーム内での知識共有を円滑にする可能性があります。
私自身の経験を交えつつまとめてみましたので、何かの参考になりましたら幸いです。
ドキュメント、残してますか？
とある機能を実装している際に、「そもそもこの仕様はなんだっけ？」「なんでこのコードの書き方を選んだんだっけ？」と、過去の意図を思い出せず時間を費やした経験はありませんか？
私もこれまで何社か経験する中で、どうしても「あとでドキュメント化しよう」と思いつつ放置したり、心理的ハードルが高くて着手できなかったりすることがありました。
そんな中、『世界一流エンジニアの思考法』を読んで、「小さなドキュメント」という考え方に触れました。ここでいうドキュメントは、完成後にしっかりした仕様書を作ることではなく、実装前や実装中に思考プロセスをサッとメモしておくような、軽量な情報共有のものです。また、機能要件やビジネス仕様のような正式なドキュメントとは異なり、エンジニアが実装時に抱く思考過程や技術的な判断材料を、簡潔な形で外部化したものです。ビジネス仕様は「何を実現すべきか」に焦点を当てることがあるのに対し、ここで述べるメモは、コードを書く際の「なぜその実装になったのか」や「どんな意図・背景があったのか」といった情報を補足するための、開発者目線の軽量なドキュメントです。
昔からやっていた「小さなメモ」
実は、振り返ってみると私自身、初学者の頃から自然とやっていたことでもありました。
例えば、マークアップを学び始めた頃、デザインカンプを印刷して「ここは<header>タグ、この部分は<nav>で…」と実装プランを書き込んでいた経験はありませんか？私はまさにそんなトレーニングをしていました。
また、ロジック実装前に「この関数は○○を計算して返す」といった下書きコメントをコード中に残しておくといった手法も、私はよく行っていました。
これらは当時、「自分の理解を深める初学者のための練習法」くらいにしか思っていなかったのですが、よく考えると、これも「小さなメモ」の一種でもありました。
とはいえ、これらのメモを永遠にコメントとして残し続けるとコードがノイズで溢れ、明瞭なコードを書くという理想から遠ざかります。
そこで、「なぜその実装なのか」「ここは後で拡張する予定」といった、コードだけでは伝わりにくい意図や非自明な仕様を補足する最低限のコメントにとどめ、
それ以外のメモは外部ドキュメント（PR説明欄、Notion、esa、Issueなど）へ移行すれば、コードをクリーンに保ちつつ必要な情報も確保できるはずです。
「小さなメモ」がもたらす開発体験の向上
がっつりとした仕様書は、大掛かりな手間や更新コストがかかるため、なかなか継続するのは難しいもの。でも、「あ、この関数はこういう背景で作る予定」とか「この箇所ではロールごとにメッセージを分ける計画」といった数行のメモなら、気づいたその場で残せます。
こうして残したメモは、自分が後から見返す際に「なぜこの書き方を選んだか」をすぐに思い出させてくれますし、新しくプロジェクトに参加したエンジニアがコードを理解する手がかりにもなります。『世界一流エンジニアの思考法』では、これを「小さなドキュメント」と呼び、アジリティや知識共有を促す要素として紹介しています。
メモまでの動線がわかりやすかった手法とツール
GitLens + PRリンクでコードナビゲーション
VSCodeのプラグイン「GitLens」を使うと、コード上からコミット履歴やPRへスムーズにつなぐことができます。これにより、「なぜこのコードはこうなっているのか」「どんな議論があったのか」といった背景情報へ最短距離でアクセス可能になります。
例えば、以下のフローでコードからPRへたどることができます。
-
GitLens をインストール・連携する
GitLensをインストールし、GitHubアカウントやgitリポジトリと連携してください。
GitLens — Git supercharged -
コード上でコミット情報を確認
コードエディタ内で、薄グレーでコードをコミット名やコミット者が表示されます。マウスホバーすると詳細情報が表示されるので、ポップアップ内の地球儀アイコンをクリックすると、そのコミットのGitHubページへ遷移します。
-
コミットからPRへ遷移
GitHub上でコミット詳細を表示すると、マージしたブランチの横にPR番号が表示されます。
そこをクリックするだけで、当該のPRページへ素早くアクセス可能です。
これで、コード（VSCode） → コミット（GitLens経由でGitHub） → PR → 外部ドキュメント（Notionやesa、Issueなど）という情報への導線が完成します。
PR説明欄に補足メモを残す
PRへ移動できれば、PR説明欄に「このロジックは将来別機能で使い回す予定」とか「この変数は後続のタスクで削除予定」など、開発時の思考プロセスや計画を短くメモできます。こうした情報が後からコードを読む際に大きな助けになります。
PRからNotionやesa、Issue管理ツールへのリンクを設置
さらに、PR説明欄でNotionやesa、Issueトラッカーへのリンクを貼っておけば、より詳細なドキュメントや「小さなメモ」へとシームレスにアクセスできます。
DX（Developer Experience）の改善へ
こうした「小さなメモ」は、開発者体験（DX）を向上させる一つの「デザイン」でもあります。
コードという情報の世界で、必要な知識に素早く辿り着ける導線を整えることは、情報アーキテクチャやUXデザインの発想に近いと言えます。
「小さなメモ」があることで、調査に費やす時間を減らし、よりスムーズに開発を進めることができます。これはチームとしてのスピードアップだけでなく、他のエンジニアや将来の自分へのギフトにもなるんです。
無理なく始める「小さなメモ」文化
もちろん、「必ずドキュメントを書け！」と強制すると、かえって面倒になり、続かないこともあります。
でも、実装中のついでにサッとコメントを残したり、IssueやPRの説明文に一文添えたり、軽量なツール（Notion、esa、GitLensのプルリクリンクなど）と組み合わせることで、自然発生的に「ちょっとメモしておこう」という気分になれます。
まとめ：「小さなメモ」が紡ぐ未来
結局のところ、「小さなメモ」は「後になって自分や仲間を助ける保険」です。
完成度100%の仕様書ではないけれど、ほんの数行の補足や思考の断片が、数ヵ月後、あるいは新規参入者がコードを読むときの大きな助けになる。
『世界一流エンジニアの思考法』で言われているような、小さなドキュメントの積み重ねは、長期的な価値を生み出し、プロジェクト全体のDXを向上させます。
ぜひ、今日の作業の中で、ちょっとメモを残してみてください。それが未来の開発者体験をより良くする一歩になるかもしれません。
最後まで読んでいただき、ありがとうございました🙏
書籍：世界一流エンジニアの思考法
Discussion