不要ソースコードをコメントアウトするなら、削除して履歴を残して😭
Contents
信じられないだろうが、バージョン管理システムへの登録や更新も「非効率的」とか「無駄な工数」とか抜かすSEもプログラマも多い。
— Yuichi Onodera (@mokemoke6502) March 25, 2020
に対して、
gitは使ってるけどコメントが
— matsuaki (@matsu4ki) March 26, 2020
・画面の修正をした
・バグを直した
・一旦コミット
とかの意味がほぼ無いコメントで埋もれてるgitは見かける https://t.co/9A6NV7nwoA
と引用リツイートしたのですが、もう少し自分で整理しておきたいと思い記事にしました。
はじめに
git でソースコード管理をしている際、仕様変更などで特定の関数自体が不要になる場合があります。 その時、対応しているエンジニアが取れる行動としては、
- 放置
- コメントアウト
- 削除
の 3 つがあると思います。 今回はこの 3 つの対応について話していこうと思います。
TL;DR
- とりあえずどこかに、なぜそうしたかの理由を書いておく
- 不要なソースコードは削除して、コミット履歴に理由を書いといてね。
1.そのまま残す
これが一番最悪なパターンです。
使われていないのに残っているということは、それだけムダな容量を取っているということになります。また、変更しないため、git の変更履歴にも残りません。コミットからなぜこのソースコードが消されていないのかの理由も探すこともできないのです。もしこのケースになっているソースコードが散乱しているシステムに出くわした場合、ソースコード的にも PJ メンバー的にもやばいと思います。ほぼ間違いなくソースコードは管理されていません。
既存コードへの対応策
バッサリと未使用のソースコードは削除するべきです。
その PJ に該当ソースコードが使われていた理由を知っている PJ メンバーがいる場合は別ですが、基本的には使用目的のサルベージは不可能だと思って問題ないです。また、使用目的が不明なので再利用される可能性も限りなく低いです。
ただし、削除する前に本当に使われていないかの検証を行う必要があります。 PJ 全体で問題定義を行うところから入ったほうが良いでしょう。
2.コメントアウトする
こちらもあまり良いとは言えません。
コードがコメントアウトされていることによってわかる情報は、
- 今は利用されていない
のみとなります。コメントアウトされた理由としては、
- 再度利用される可能性がある
- とりあえず動作させたいから
- メモ
などが考えられますが、どれなのかは第三者から到底把握できるものではありません。また、このようにコメントアウトするエンジニアのコミット履歴を確認しても「とりあえずコミット」や「一旦コミット」と意味のないコメントを記載しているか、別のコミットに滑り込ませている場合が体感として多いです。
既存コードへの対応策
こちらも、問題 1 と同様に削除するべきだと思います。 しかし、こちらは使用されていないことが分かっているので問題 1 よりはスムーズに削除できると思います。注意事項も問題 1 と同じです。
どうしてもコメントアウトを行う場合は、なぜコメントアウトにするのかをコメントアウトするソースの先頭やコミットのコメントに必ず記載してください。
また、メモなどでコメントアウトしている場合はNOTE:を、動作が明瞭でないソースコードにはXXX:などのアノテーションコメントを入れることも検討しましょう。IDE 側で検索やハイライトが行えるため見通しが良くなります。
3.削除する
ソースコード管理ツールを利用している状況下では、この選択が一番良いです。
削除する際には、なぜ削除を行うのかという理由をコメントで残しておきましょう。 また、コミットは削除のみで行うことにも注意しておきたいです。他の変更と混ぜてしまうと何の変更を行ったのかが分かりづらくなります。 再利用される可能性がある場合は、チケットなどにコミット番号を残しておくと良いと思います。git はコミット番号で簡単に検索することができるので、コミット番号と簡易的な説明以外は必要ないかもです。
さいごに
大事なことは、数カ月後に誰が見てもなぜこのような処理にしたのかを把握できる状態にしておくことです。
なので、既存のソースコードをリファクタリングで削除する際にも、必ず「XX の経緯でリファクタリングを行うことになり、削除した」などのコメントを残すことが大切だと思います。Backlog などのプロジェクト管理ツールを利用している場合は、対応チケットの番号を記載し、具体的なやり取りはチケットに記載する方法でも問題ないです。
また、今後運用していく際にで同じ轍を踏まないようにするため
- wiki などのドキュメントに運用方法を記載する
- ソースコードレビューでリジェクトする
- PJ 管理ツールへのリンクがないコミットはコミットできないようにする
- PJ のソースコードを定期的にアナライズする
などの対策も必要です。 とはいえ、実際にやるとやはり大変です。 まずは既存メンバーのコメントを見直すなど、できることから行っていくことが大切だと思います。
