プログラムにコメントを書くべきなのか、書くべきではないのか、書くとすればどんなコメントが良いのか？そんな疑問があったので、自分なりの考えを書いていきます。
リーダブルコードも参考に書いています。まだ読まれていない方は以下から読んでみてください。
目次
コメントに記載しないほうが良いこと
読み手にとって自明であるもの。まずは、プログラムの読み手が誰に当たるのかが重要になります。
その上で、読み手にとって情報が得られない自明なコメントは控えたほうが良いでしょう。
読み手が、プログラムについて理解がある場合、次のようなコメントは必要ありません。
ソースコードで表現されているのでコメントの下にあるソースコードを読めば理解ができます。
public class Main {
// main関数で、最初に実行される関数
public static void main(String[] args) throws Exception {
// ログ上にHello Worldと表示させる
System.out.println("Hello World");
}
}ただし、読み手がプログラム初心者などの場合には、コメント量を多くして、分かりやすくしても良いでしょう。
他の例として、読み手がビジネスロジックについて詳しい場合、次のようなコメントは必要ありません。
どれも関数名でやっていることがわかりますし、ロジックに知見があるのであれば理由を明記する必要もないでしょう。
public class Main {
public static void main(String[] args) throws Exception {
// ロジックを実行する関数を呼び出す
runLogic();
}
// ロジックを実行する関数
private static void runLogic() {
// データを取ってくる
fetchData();
// データをBに移し替える
tranceferDataToB();
// 成功とログに表示する
System.out.println("成功");
}
// データを取ってくる関数
private static void fetchData() {
System.out.println("データを取ってくる");
}
// データをBに移し替える関数
private static void tranceferDataToB() {
System.out.println("データをBに移し替える");
}
}コメントに記載したほうが良いこと
読み手に伝えたいことです。 例えば、次のようなコメントは入れたほうが良いでしょう。
- 調査結果
- 未完成な部分
- 理由
調査結果
ソースコードに対して調査を行って、結果を得られたものであれば、調査結果を書いておくことが望ましいでしょう。
// Aと比較してBの方が40%高速であった
B();未完成な部分
未完成なままソースコードを誰かに読んでもらうケースが有る場合ですが、
対象の部分が検討漏れなのか未完成なのかがわからなくなってしまうので、記載するべきでしょう。
// TODO: B処理の後に必要なC処理は後で作る
B();
// C();理由
背景が存在する場合にはそのソースコードを書くに至った背景を記載することが望ましいでしょう。
int MAX_THREADS = 8; // 〇〇人同時アクセスでも耐えられるようにするためまとめ
ソースコード中に書くべきコメントは状況によるものがほとんどです。その中でも、誰がそのソースコードを読むのかを意識してコメントを記載すると、迷うことも少なく、適切なコメントを行うことができるでしょう。