「なぜ？」にパニックなし！設計意図を伝える「3行ログ」術

コーヒータイム、いかがお過ごしでしょうか。西山です。さて、今日はちょっと実務的な話です。新人の頃は先輩に「なぜこの書き方にしたの？」と聞かれ、パニックになった経験、ありませんか？実はその答え、コードの中に全部あるわけではないんです。

コードは「怎么做」しか語らない

ソースコードを見れば、どんな処理が行われているかは分かりますよね。でも、なぜそのアルゴリズムを選んだのか、なぜこの変数名にしたのか、といった「意図」までは読み取れません。これが、レビュー時に「なぜこうしたの？」と聞かれる主な原因です。意図は言語化しないと、チーム内に共有されません。

解決策は「3行ログ」の習慣化

そこでおすすめしたいのが、コミットメッセージやコード内のコメントに「3行ログ」を書くことです。1行目に「何をやったか」、2行目に「なぜそれを選んだか（代替案との比較など）」、3行目に「将来のメンテナーへの注意点」を書きます。これだけで、後続の開発者の理解度が劇的に変わります。

AIに整理させるのも手

もし「どう書けばいいか迷う」という場合は、生成AIに「この変更点の背景を整理してコメント文案を作成して」と投げかけてみるのも手です。ただし、AIの出力を鵜呑みにするのではなく、自分の思考を整理するプロセスとして利用するのがポイントです。意図を言葉にする練習になり、一石二鳥です。

プロセスこそが資産になる

最近では、生成AIを活用したハッカソンなどで「成果物よりも過程を競う」という視点も注目されています。コードそのものより、そこに至るまでの判断プロセスこそが、チームの知恵として残る財産だからです。自分の思考の痕跡を丁寧に残すことで、より良い開発環境が築けていきます。

次回のレビューで、自信を持って意図を説明できるようになりましょう。その一歩が、チームの信頼を深めます。それでは、また次のコーヒータイムで！