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