2018年1月15日

【コンサルタント散歩】

～ソースコードのコメントは見やすく！分かりやすく！～

皆さんはコーディングをする際にコメントはどの程度記載するようにしていますか。筆者の感覚では７（プログラム）対３（コメント）の割合がソースコードの内容がごちゃごちゃして見づらくなく、後々見てもわかりやすいのではないかと考えています。ここで、どのような内容のコメントが必要で、不要なコメントは何なのか考えてみました。

必要なコメント

〇 全体の流れが分かる要所々々でのコメント

〇 COBOL言語で言えばFUNCTIONで定義した関数の説明

〇 設計書の内容を実装するにあたり特殊なことを行わないといけない箇所

不要なコメント

✕ コーディングした内容をそのまま日本語にしただけのコメント

✕ コメントを付けることにより誤解を招く記載

✕ 設計書からそのまま内容をコピペしたコメント

とは言え、実際のプロジェクトではコーティングルールに則ったうえで、必要なコメントを記載しなければならないので注意が必要です。

筆者が複数のプロジェクトで不要なコメントを記載していると強く感じたのがプログラム設計書の内容をコーディングの際にコメントとして記載しなければいけないプロジェクトでした。コーディングルールとして記載しなければいけないのでしょうがないのですが、チームリーダーの立場で途中から参画した大規模なプロジェクトだったため、大変苦労した覚えがあります。なぜならソースコードの確認とソースコード上のコメントがプログラム設計書と同じ内容か確認しなければいけなかったからです。本来であれば、ソースコードの確認とコメントの内容が適切かどうか確認を行えばよいはずです。

プログラム設計書の内容をコメントに記載した場合は、設計書の記載内容に文言の統一化や品質向上施策による変更が入ると全てソースコードのコメントを修正しなければいけない作業が発生します。テストが完了しているソースコードに修正が入った場合はデグレテストを実施しなければいけないため、作業が増えて大変になります（ソースコードのDIFFのみでは許されないプロジェクトでした）。結果として、当該プロジェクトのソースコードはごちゃごちゃして見づらく、分かりにくい、そして作業負荷が掛かるものとなってしまいました。

当該プロジェクトのようなコーディングルールでは難しいかもしれませんが、要所々々に必要なコメントを記載し、見やすく、分かりやすいコーディングをするよう気を付けていきましょう。

2018年1月

※ 関連ページ 「情報化企画（システム企画）・プロマネ支援サービスのご案内」