2023.11.29

開発コードのコメントの付け方

コメントとは？

プログラム言語で書かれたソースコードに対して、覚え書きとして記述される文章のことです。開発者自身や他の開発者に開発の引き継ぎをする際にどのような処理を記載しているかわかるようにコードにコメントを記述します。

コメントの付け方ですが、以下の点について注意しながら記述しています。

• 他の人が読んでも理解できる文章か
• どのような処理であるかわかりやすく記述されているか
• 無駄なコメントはつけない

コメントは自分以外の人も目を通すこともあるため、記述に注意が必要です。開発の期限に追われ、コメントつけが疎かになってしまうこともあるため、コメントはコードを記述したらすぐにつけるようにしています。また全てのコードを記述し終えた後にも再度コメントをつけ忘れていないか再確認しています。
それだけコメントつけは重要な作業と言えます。

コメントは多過ぎても読みづらくなります。
ですので、私は必要以上にコメントはつけないようにしています。特に条件分岐に関しては大きな機能開発になると条件分岐が多くなる場合がありますが、全ての条件分岐につけるのではなく、説明が必要な条件分岐、複雑な条件分岐に記述するようにしてます。全てに記述するとコメントの量も多くなってしまいます。本当に伝えたい、重要と思える箇所に記述した方が自身や、他の開発者も見やすくなると考えています。

コメントの書き方

次に良いコメントと悪いコメントの記載方法について説明したいと思います。
まずは以下のコメント例を見てください。

良いコメント

悪いコメント

上記の条件分岐ですが、良いコメントは変数名がどのような物であり、どのような条件かを記述しています。一方、悪いコメントは変数名と条件しか記述していません。これでは条件分岐で何をしたいのか内容が伝わってきません。開発者本人は理解できるのかもしれませんが、他の人が見たときに何をしたい処理なのかが伝わりません。条件分岐の前後の処理や変数名でなんとくどのような処理をしているのか解読することは可能ですが、それは解読する時間がかかってしまうため、良いコメントとは言えません。
良いコメントは読む側に負担をかけず、内容を理解しやすいように記述する必要があります。そのために記述する文章が長くなったとしても今後のことを考えると保守しやすくなります。

様々な業務で複数の担当者が書くコードを見ていると、コメントの位置が誤っているケースに意外と多く遭遇します。コメントのつける位置についても説明します。コメントは対象コードの上につけることが一般的で、弊社で開発しているシステムのコードも上につけるように統一しています。 以下のコメント例を用意しました。

良いコメント

​​悪いコメント

良いコメントの付け方が一般的ですが、実は悪いコメントの記述をする開発者も意外といます。他の人のコードレビューをすると、たまに上記の悪いコメントで記述している箇所を見つけます。
行末コメントが悪いコメントとして取り上げられるのは、行末コメントだと対象コードを修正した場合行末コメントの桁位置ズレが起きます。また処理コードの後ろに書かれると、コード自体も見づらくなるため、保守しづらくなります。よって基本は良いコメントのようにコード上に記載するようにしています。

まとめ

ここまで私が実施しているコメントの付け方について述べてきました。記載するコメントは日本語だからコードを記述するより簡単だと思われますが、私はコメント付けの方が難しいと考えています。
コードは記述するルールが明確に決まっていて、ルールを無視すると警告が表示されます（使用しているフレームワークによる）が、コメントは誤った記述をしたとしても特に警告は表示されないため、開発者が正しいか、理解できるコメントか判断して記述する必要があります。

今後も開発していく上で、今一度コメントの重要性を開発メンバーで共有し、正しい、わかりやすく、意味が理解できるコメントになっているか再度確認し保守しやすいコードを目指していきます。