コメントの書き方

こんにちは,インターン生の鳥井保秀と申します.

この記事では読みやすいコードの書き方と題して,コードの見た目を整え可読性の高いコードを書くための手法をご紹介しています.

前回はコードの可読性を意識することの重要性,可読性を意識することのメリットをご紹介しました.ではどのようにすれば可読性が高くなるのか,第二回である今回は読みやすいコメントの書き方について,私の主観を交えながらご説明したいと思います.

読みやすいコメントの話をするにあたり,まず初めに述べておくべきことは,どんなコメントでもないよりはある方がましということです.これは所属している研究室でシステム改修を行っている一個人の経験からくる意見ですが,例えば,
・メモ書き程度の粗雑なコメント
・誤った内容のコメント
等といった読みにくいコメントであったとしても,コメントがない部分よりはある部分のほうがはるかに問題発生個所を特定しやすく,修正が容易です.そのため慣れないうちはコメントの読みやすさを意識しすぎずに,とにかくコメントを書く癖をつけたほうが良いと思います.

そのことを前提に,しかしながら読みにくいコメントが多い部分はやはり読みにくく,ソースコードの理解に時間がかかる要因となってしまうため,できればそのようなコメントはないほうが望ましいです.ではどのようにすれば読みやすいコメントになるのでしょうか.

まずメモ書き程度の粗雑なコメントについてですが,もともとコメントはメモをするものなのでこれ自体に問題はありません,しかし少し工夫をすることでより読みやすいコメントに変えることができます.それはコメントに見出しを付けることです.例として
TODO: 後でやること
FIXME: 要修正
WARNING: 注意
HACK: 正しいがきれいではないコード
XXX: なぜ動くのかわからないコード
といったコメントの意味を示す文字列をコメント本文の前に加えるという記法(アノテーションコメント)があります.この記法を用いることでコメントが何を表しているのか瞬時に理解することができ,大きな手間をかけることなくコメントを読みやすくすることができます.

次に誤った内容のコメントに関してですが,誤った内容のコメントが発生する原因は大きく2種類に分けられると考えます,一つはプログラムの理解不足やソースコードそのものの誤りからソースコードとコメントが乖離してしまうケース,もう一つはプログラムの修正がコメントに反映されていないケースです.前者に関してはコメントの書き方の工夫では対処できず,製作者の理解やソースコードの修正が必要となりますが,後者に関してはコメントに内容を意識することで多少防止することができる可能性があります.それはコメントを書く際にそのコードが何をしているのかではなくそのコードが何をしたいかを意識することです.言い換えれば,コードの手法ではなくそのコードを書いた目的を記述するということです.プログラム修正において,同じブロック内ならば目的が大きく変わることは手法が変わることに比べて比較的少ないため,目的を書いておくことによってソースコードの修正の影響を受けにくくなり,逆に手法が固定されないことでソースコードの修正がしやすくなります.

今回は読みやすいコメントについてご紹介しました.読みやすいコードのためには,少なくともソースコードを読んで意図の読み取れない部分にはコメントが必要となるため,読みやすいコードのためには読みやすいコメントを書けるようになる必要があります.

しかし前半の話と矛盾するようですが,コメントが多すぎるとかえってコード全体の見通しが悪くなってしまいます.もし,ソースコードの変数や関数名から意図が読み取れるならばコメントは最小限で済みます.そのため次回はコメントに頼りすぎずに読みやすいコードを書くために,変数や関数の命名についてご説明しようと思います.

興味を持たれた方はお気軽にお問い合わせください。

インターンシップへの申し込み・お問い合わせ先

インターンシップへの申し込み・お問い合わせ先
メールでのお問い合わせは、下記フォームに入力して送信してください。
ご氏名 (例)山田 太郎
メールアドレス 半角英数字:ご入力間違いのないようにご注意ください
メールアドレス(確認用) 半角英数字:ご入力間違いのないようにご注意ください
電話番号 (例)0354339211 ※ハイフン抜きで入力してください
題名
お問合わせ内容

アーカイブ

カテゴリー