業界の悪習

Question

私が参加しているプロジェクトではこれまで改訂履歴に関するルールは存在しなかったのですが、これから改修箇所はコメントで修正履歴を残すことが義務付けられることになってしまいました。

// yyyy/mm/dd daresore MOD Start
//// yyyy/mm/dd daresore DEL Start
//// // hogeMethod(param2);
//// yyyy/mm/dd daresore DEL End
// yyyy/mm/dd daresore daresore DEL Start
// // fugaMethod("");
// yyyy/mm/dd daresore daresore DEL End
// yyyy/mm/dd daresore irdaresoreof MOD End
hogeMethod(param);

バージョン管理システムを利用しているのにコメントで修正履歴を残すことは悪習だと思うのですが、皆さんはどう思われますか？
また、もうこんな悪習は嫌だ！って話ありますか？

Answer 1

履歴コメントが入っているコードを引き継いで自分がコーディングルールを決められる立場になったものは、新しい修正時には履歴を入れないようにしています。

1メソッドは長くても20行とかにしていた場合、コードが履歴に埋もれてしまうとそれが守られなくなりますね。
コードの単位を短くするのは、その単位で全体を眺めて処理を把握することを容易にするためだと思いますので、コードが履歴に埋もれてしまうと全体を把握する際にノイズが乗ってしまいます。

この辺のコメントの入れ方を含むコーディングルールは、多くの有名なコーディングスタイルでは否定の傾向があるかと思いますし、個人的には、履歴コメントがあるとコードの品質は低下すると思います。

もし履歴コメントを入れる提案が出たとしたら、上記理由と併せてバージョン管理システムで履歴を確認する手順を確立させて反論し、断固阻止します。

でも、バージョン管理システムをつかいこなせない（しようとしない）メンバーで開発する場合は仕方ないかもしれませんね。

その他の悪習もたくさんありますが、その中でも履歴コメントは最悪の部類ですね...

Comments

[sho_cs]

うちで履歴を残せと言い出したのが顔も知らない、コードも書かない、コードを読むかも怪しいお偉いさん・・・

後は何でもExcelで管理しようとするのも悪習。

[argius]

「素人が口を出すな！」って言いたいところですね。

Excelは、構造を表す目的には向いていないと思いますが、1ファイルに複数の書類（シート）をバインドできるのは便利なんですよね。
何もかにも全部Excelでやるのは反対ですね。

[sho_cs]

1ファイルに複数の書類（シート）をバインドできるのは便利なんですがシートのタブが満杯になった設計書の恐ろしいことと言ったら。
こういうのに限って中身が空だったり、一見書いてある風に見えて役に立たないなどよくあると思います。

Answer 2

ソースコードが見づらくなるのは同意しますが、
あなたの利用しているバージョン管理システムで更新履歴は見やすいのでしょうか？

現状のバージョン管理システムを用いてファイルの更新履歴を見る方法を周知させ、
それが使いやすいことを納得させた上で、
改めて更新履歴を消す提案をするべきです。

更新履歴を見るために長々と複雑なコマンドを打たないといけなかったりすると、反対するユーザも出てくるでしょう。
いかに「バージョン管理のほうが見やすいだろ！？」ってのを訴えられるかが重要だと思います。

Comments

[sho_cs]

チーム内ではコーディングを行わない管理者もGitとSourceTreeを使用し、履歴を確認しています。
履歴を残せと言っているのは、さらにその上の人たちで、ソースを紙出しで見たいようです。
改修時に提出するdiffで十分だと思うんですけどね。

[TaMaMhyu]

生ソースコード上に履歴を残すことが目的ではないですよね…
このソースコードはどのような更新が行われたかの一覧が何らかの書類の形で提出できればいいのではないでしょうか？
書類ベースで見るとなると、差分だと、逆に見づらいかも知れません。そのレベルの目視なら更新前全文と更新後全文を並べた方がいいのではないかと…

[sho_cs]

何らかの書類の形ではなくソースの現物を見たいようで、そのソースは試験を通したもの（コメントも含めて一致する）ではなくてはいけないようです。

今まで同じようにやってきたからこれからも同じようにやるという思考停止です。

[TaMaMhyu]

業務改善をする余地がもしあるのであれば、複数の改善案を用意して利点と欠点を並べて説明するしかないですかね…

[sho_cs]

改善案を提出することが出来る範囲では改善進められているのですが…
・MarkDownを使った資料作成
・Jekins導入
・SubversionからGitへの移行
・GitLab導入（準備中）

なんとか説明してみようと思います。