更新履歴・修正履歴をソースコードに残すこと

#🌱

そういう現場にしか当たらないのでどうにか無くすためのメモする。

「更新履歴・修正履歴をソースコードに残す」とは以下のようなソースコード中にコメントで修正履歴を入れてしまうこと。

code:memo.c

‘START 2017.07.01 【修正】会員番号の桁数増加対応(5桁→6桁)　詳細設計P-4400 担当：山田太郎

‘元のソース（コメント化）

修正後のソース

‘END 2017.07.01 【修正】会員番号の桁数増加対応(5桁→6桁)　詳細設計P-4400 担当：山田太郎

ref: ソース修正時にコメント文に残しておきたい項目（参考例付き）

上記のような文化を無くしていくには、そもそも GitやSubversionなどのバージョン管理システムが不可欠である。

とはいってもバージョン管理システムを使っていてもなおこの文化が残ることがよくある。理由としては以下が挙げられる。

保守メンバーが障害が起きたときに確認とき便利らしい

うまく言いにくいが既存の開発フローが曖昧で更新履歴・変更履歴があった方がよい文化がある

更新履歴・修正履歴をソースコードに残すことのデメリット

ソースコード中に修正履歴を残されると、

grepの時に邪魔、ストレスになる

ソースコードを読むときに邪魔

diffがうまく機能しなくなる

どれが生きているコードかわからなくなる

保守性云々言われるがとにかく開発するときに邪魔なのでやめてほしい。

コメントを残す理由

まずは修正を加えた際に、コメントを残しておくべき理由から。

コメントが活躍するのは修正を行った後になります。再度カスタマイズなどで手が入れることになれば、コメントが残っていることで、その経緯を追いやすくなります。さらにコメントが残っているおかげで、せっかく修正した箇所をつぶしてしまうリスクもなくなります。

コメントを残す行為は面倒かもしれませんが、ソース修正時のお約束事とでも言うのか、鉄則だと思ってもらってよいでしょう。後々のメンテナンスが楽になりますので、必ず次に挙げるような情報を含めて残しておかなければならない、という認識を持っておくようにしてください。

ref: ソース修正時にコメント文に残しておきたい項目（参考例付き）

逆に更新履歴、修正履歴がないことをポジティブな言い方に直すと

grep

grep結果が見やすくなる

生きているコードが判別しやすい

(C言語の場合) /* */の間のコメントアウトを生きてるコードと思うことが無くなって、見間違い・調査ミスが起こらなくなる

(C言語の場合) #ifdef 0のような死んでいるコードを生きているコードと思うことがなくなり、見間違い・調査ミスが起こらなくなる

ソースコード

余分な情報が無くなることで認知的負荷が減る

余分な情報が減って見やすくなる

追加・修正・削除がしやすくなる

どれが生きているコードかわかりやすくなる

diff

(GitHubやWinMergeなどのサイドバイサイドで見ることができれば)レビュー時に負荷が小さくなる

適切な差分を見ることができる

Gitでよく見るunified 形式で見る際に、どれが削除部分かがわかりやすくなる

説得をする場合、恐怖(またはネガティブ)で説得する場合よりポジティブな説得の方が受け入れやすいらしい

ref: 『事実はなぜ人の意見を変えられないのか-説得力と影響力の科学』３　快楽で動かし、恐怖で凍りつかせる（インセンティブ）

更新履歴はバージョン管理システムがあれば別にいらなくなる。

ソースコードのヘッダにコメントを残すのは自分は別に良いと思う。この場合のヘッダというのは以下のような更新履歴。

code:memo

日付修正内容修正者

2020/06/01 64bit化対応 John Doe

2023/02/02 会員番号の桁数増加対応(5桁→6桁) 山田太郎

問題は様々なステークホルダーを納得させるのが非常にきつい場合がある。

バージョン管理システムをうまく導入する

Proj: 会社で構成管理(Git)ができる人を増やす

(書き途中)

Shift_JIS環境へのGit導入

Gitハンズオン

確認用

Q. 更新履歴・修正履歴をソースコードに残すこととは

Q. 更新履歴・修正履歴をソースコードに残すことのメリット

Q. 更新履歴・修正履歴をソースコードに残すことのデメリット

Q. どうやれば更新履歴・修正履歴を無くしていけるか

Q. どうやればバージョン管理システムをちゃんと使ってもらえるか