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

新規でシステムを納品して、保守をしていくことになれば、どこかで既存システムに修正を加える必要性が出てくることもあります。それはバグ対応かもしれないし、新規機能の追加かもしれないし、機能カスタマイズかもしれません。

そうしたときは、納品時のバージョンからの差分が分かるように、修正箇所には必ずコメントを残しておきましょう。そしてコメントの内容にも気を配るようにしてください。

コメントを残す理由

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

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

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

コメント文に残しておきたい項目

ソース修正時にコメントとして残しておきたい項目は次の通り。

• 日付
• 担当者
• 修正内容・経緯
• 設計書とのリンク番号
• スタートとエンド
• 新規、修正、削除の情報
• 修正前のソース

 

日付

いつその修正を加えたのかが分かるように、日付情報はコメント内に残しておきたいものです。つい最近加えられた修正なのか、ずいぶん昔に手が加えられた内容なのかが分かることで、その後の対応も変わってくるかもしれません。

西暦、和暦は問いませんが、フォーマットは統一する形で日付情報を残しておきましょう。

担当者

修正を行った担当者名を記載しておくと、修正の経緯や詳細を確認する際に役立ちます。修正が入った内容について、詳細を誰に聞けば分からない状態はエンジニアを困らせる要因になりますので、担当者名もコメント内に残しておきます。

修正内容・経緯

修正内容はソースを追えば分からないことはないですが、プログラミング言語よりも日本語で書かれていれば、一見しただけで理解ができます。作業効率が高くなるのは言うまでもありません。

また修正を行った経緯についても残しておくことで、その修正を残しておくべきか、つぶしてしまってもよいかの判断がつきやすくなり、その後の業務を円滑に進めることができます。

設計書とのリンク番号

ソースを修正したらコメントを残すだけでなく、設計書も修正するのが鉄則です。そして設計書の修正箇所とリンクできるような番号を残しておくと、その後の対応にあたるプログラマーが喜びます。その後の対応者は自分になるかもしれませんし、自分になったらなったで「あの時の自分グッジョブ！」と思うはず。

スタートとエンド

修正箇所がどこから始まって、どこで終わっているのか、という情報がないと、いったいどこからどこまでの範囲で手が加えられたのかが分かりにくくなります。スタートとエンドの情報は必ず入れるようにしましょう。

新規、修正、削除の情報

ソースは修正されるだけでなく、新規で付け加えられたり、削除されることもあります。どのような修正対応を行ったのかもコメントに残しておきたいものです。

修正前のソース

新規の場合は別ですが、既存のソースを修正するなり削除するなりした場合は、修正前のソースはコメント化して残しておくようにしましょう。そうすることでどんな変化があったのかが分かりやすくなります。特に削除の場合は一度消してしまうと、修正履歴を追うのが不可能になってしまうので、必ずコメント化して残しておきます。

コメント文の参考例

それではコメント文の参考例について・・
あくまで参考程度なので、これが正しいというわけではありません。もっと分かりやすいコメントの書き方もあると思います。

新規

修正

※必ず修正前のソースはコメント化して残しておきましょう

削除

※必ず削除対象となったソースはコメント化して残しておきましょう

 

おわりに

処理に直接影響は与えないコメントですが、その役割はとっても重要です。修正箇所がどこだか分からなくなって困るPGがいなくなるように、元ソースからの追加・修正・削除時には、一見すればどのような処理が行われたのかが分かるようなコメントを残すようにしましょう。