更新履歴・修正履歴をソースコードに残すこと
そういう現場にしか当たらないのでどうにかなくすためのメモする。
「更新履歴・修正履歴をソースコードに残す」とは以下のようなソースコード中に修正履歴を入れてしまうこと。
code:memo.c
‘START 2017.07.01 【修正】 会員番号の桁数増加対応(5桁→6桁) 詳細設計P-4400 担当：山田 太郎 ‘元のソース（コメント化）
修正後のソース
‘END 2017.07.01 【修正】 会員番号の桁数増加対応(5桁→6桁) 詳細設計P-4400 担当：山田 太郎 とはいってもバージョン管理システムを使っていてもなおこの文化が残ることがよくある。理由としては保守メンバーが障害が起きたときに確認とき便利らしい。
ソースコード中に修正履歴を残されると、
grepの時に邪魔
ソースコードを読むときに邪魔
diffがうまく機能しなくなる
保守性云々言われるがとにかく開発するときに邪魔なのでやめてほしい。
コメントを残す理由
まずは修正を加えた際に、コメントを残しておくべき理由から。
コメントが活躍するのは修正を行った後になります。再度カスタマイズなどで手が入れることになれば、コメントが残っていることで、その経緯を追いやすくなります。さらにコメントが残っているおかげで、せっかく修正した箇所をつぶしてしまうリスクもなくなります。
コメントを残す行為は面倒かもしれませんが、ソース修正時のお約束事とでも言うのか、鉄則だと思ってもらってよいでしょう。後々のメンテナンスが楽になりますので、必ず次に挙げるような情報を含めて残しておかなければならない、という認識を持っておくようにしてください。
逆に更新履歴、修正履歴がないことをポジティブな言い方に直すと
grep
grep結果が見やすくなる
例えば/* */の間のコメントアウトを生きてるコードと思うことが無くなって、見間違いが起こらなくなる
ソースコード
余分な情報が減って見やすくなる
修正がしやすくなる
diff
(GitHubやWinMergeなどのサイドバイサイドで見ることができれば)レビュー時に負荷が小さくなる
適切な差分を見ることができる
説得をする場合、恐怖(またはネガティブ)で説得する場合よりポジティブな説得の方が受け入れやすいらしい
ソースコードのヘッダにコメントを残すのは自分は別に良いと思う。この場合のヘッダというのは以下のような更新履歴。
code:memo
日付 修正内容 修正者
2020/06/01 64bit化対応 John Doe
2023/02/02 会員番号の桁数増加対応(5桁→6桁) 山田 太郎
問題は様々なステークホルダーを納得させるのが非常にきつい場合がある。
バージョン管理システムをうまく導入する
shift-jis
(書き途中)
確認用
Q. 更新履歴をソースコードに残すこととは
Q. 更新履歴をソースコードに残すことのメリット
Q. 更新履歴をソースコードに残すことのデメリット
参考
ソースコードの修正履歴は誰が見るか
ソースコードのレビューア
トラブル発生時の保守エンジニア
影響調査時の保守エンジニア
これを公開してしまうということに戦慄してしまうが資料としては便利
コメントを残す理由
まずは修正を加えた際に、コメントを残しておくべき理由から。
コメントが活躍するのは修正を行った後になります。再度カスタマイズなどで手が入れることになれば、コメントが残っていることで、その経緯を追いやすくなります。さらにコメントが残っているおかげで、せっかく修正した箇所をつぶしてしまうリスクもなくなります。
コメントを残す行為は面倒かもしれませんが、ソース修正時のお約束事とでも言うのか、鉄則だと思ってもらってよいでしょう。後々のメンテナンスが楽になりますので、必ず次に挙げるような情報を含めて残しておかなければならない、という認識を持っておくようにしてください。
メモ
2012-08-15
2013-01-29
2025-03-20.
令和にもなって、まさかこんなコード残ってないですよね？
「バージョン管理してるんだから、この修正履歴の行いらないですよね？」って昔上司に聞いたら、
「いやいや、バージョン管理ツールだといちいち履歴を見ないとどんな変更してたか確認できないんだから、これの方がいい」
って言われてれ、「あ、終わったー」と思ったのはいい思い出です☺️
関連