コメントを書くコツ
はじめに
皆さんはプログラムを書く時コメントは書いていますか？
入門講座では言語仕様としてのコメントの文法は教わりますが、どういうことをコメントに書くべきかは教えてもらえません。
コメントはなんでも書けばいいわけでもなく、適切に書かなければいけません。
しかしこのニーズは案件ごとに違うし、企業のコードスタイルによっても違います。
そのため、コメントについての議論を自分から調べないと考える機会もあまりないと思います。
ここで勉強してみましょう。
書かない方がいいコメント
言語やフレームワークの説明
入門書に書いているレベルの言語標準関数の説明は意味がないので書きません。
public function addSales(int price) {
// salesにpriceを加算する。なお、salesはクラス変数だがJavaではthisは省略できる。
sales += price;
// コンソールにsalesの値を表示します。salesはint（整数）型のままでは構文エラーになるので、
// String(文字列)型にキャスト(型変換の事)をしてから使用します。
System.out.println(String.valueOf(sales));
}
どうでしょうか？Javaを1時間以上勉強した人ならコメントがなくても理解できると思います。
むしろ邪魔です。
え？入門書にはこういうコメントがある？
そうですね。書いている場合もあります。
なぜなら入門書はこれを読めない人が読めるようになるために説明を入れてあるから。
でもこの記事を読んでいる皆さんには必要ないコメントです。
え？Javaは勉強をした事ないからこの位はコメントで教えて欲しい？
大丈夫です。
これくらいGoogleかChatGPTにコピペすればもっと分かりやすく教えてもらえます。
例外的に書いてもいい、または書いた方がいい場合。
自分だけでなく、そのプロジェクトに関わる人の大半にとってググらないと分かりづらいであろう関数の使い方は説明があってもいい。
例えば、ビットシフトやアドレス演算など、あまり使わない演算子などは分かりにくいかもしれない。
他には、GoogleAPI連携などの、外部ライブラリの関数は引数の指定も難解なためコメントを書くか、別途使い方のマニュアルを用意しないと書いた人以外修正できなくなる。
最悪、ライブラリの提供元がサイトを閉じたら調べる事もできない。
それはそうと、こういうのはラッパー関数、ファサードクラスといったものを用意して、他のメンバーはAPI仕様を知らなくても自分のコードに取り込めるようにするべきです。
詳しく書いた方がいいコメント
大きな流れの中で、どの辺りをやろうとしているコードなのかが分かる。
アクション設計書の見出しになるような事は書くべきです。
というより、アクション設計書があるなら、まず処理の流れをコメントで書いておいて、
そこに対応するコードを書いていくようにすれば実装漏れも防げるし、わかりやすいソースコードが出来上がります。
ただし、処理の流れの１つ１つを関数に切り出す事を徹底できている場合は、後述するJavaDocなどで分かるので省略しても読める場合はあります。
public function saveSales(SalesBean bean) {
// 購入代金を取得。
int price = bean.getPrice();
// 売上に購入金額を加算する。
salesLogic.addSales(price);
// 売上テーブルの現在売上を更新する。
salesRepository repository = getManager();
repository.saveSales(sales);
// フラッシュメッセージを画面に表示する。
messageUtil.flashMessage("購入処理完了しました。");
System.out.println(String.valueOf(sales));
}
計算ロジックなど、内容が難解なもの。
コメントがないと何を計算しているのかよく分からないもの。
あまりに複雑な場合、そこに全部書くとコメントでコードが埋まるため、設計書の掲載箇所だけ書くテクニックもあります。
// 切り捨ての価格を取得
int price = getOrder(int id).getPrice().roundOff();
// 梱包計算を行う
// @see 梱包計算仕様 2章３項
int packageNum = ((x + y / 256) / z % 5) + col1 + col2 + col3;
// 値引き額の決定
int discount = 0.2 * packageNum * continueYear * pref;
クラスコメント・関数コメント(JavaDoc,PHPDoc等)
クラスコメント
なんの為のクラスか、どういうタイプのクラスかが分かるように書く。
ただし、フレームワークが指定するディレクトリ名や、クラス名から明白な場合はさほど重要ではない。
関数コメント
最重要。
特にpublic関数のコメントは必須です。
これが書いていないとコードレビュー通らないかもってくらい重要。
作成者以外が関数の中身を読まなくても利用できるようにする。
関数処理内容・引数・戻り値を詳しく書く。
ここがあやふやだと、使う人はイチイチソースコードを読まなければいけなくなる。
せっかく部品として切り出したのに、使う時は分解して調べないといけないようだと勿体無いし、
最悪、時間をかけて全く同じものが別の名前で量産されていく事になる。
関数のマニュアルとも言える。
アノテーションを使う事で記法も統一できる。
vscodeやeclipseなどの統合開発環境、高機能エディタでは関数を呼び出す箇所にマウスホバーすると、関数
コメントがヒントチップとして表示されるので、いちいち実装部を見る必要がなくなります。
/**
* 店舗テーブルから店舗情報を取得する。
*
* @param string $code 店舗コード(5桁の0埋め)
* @return Store 店舗エンティティ
*/
public function getStoreByCode(string $code) {
中略
}
型は完璧で究極のコメント
静的型付け言語の場合、関数の型を指定するとその型の値や参照しか渡せなくなる。
つまり、これは関数の作成者から利用者へのコメントとしても機能しています。
ただしコメントと違い、こちらは利用者は違反できません。
ちなみに利用者の中には１時間後の自分も含まれています。
この関数を呼び出す側のコードは、この関数呼び出しの行よりも前にSalesBeanクラスを生成しないといけない事も確定するので、処理の順番を読み解く役にも立ちます。
引数と戻り値の型を見るだけでもある程度の処理内容は想像がつきます。
ちなみにjavascriptは動的型付ですが、関数コメントに型を書いておくとどういう値が入ればいいのか判断できます。
public function saveSales(SalesBean bean) {
まとめ
いかがでしょうか？
なんとなく雰囲気は掴めたでしょうか？
要するに、そのコードの部分だけを見れば理解可能なコメントは必要性が低い。
他のソースファイルや、設計書を調べたり、作った人に聞かないと分からない箇所ほどコメントの価値が高い、という事です。
どうすれば読みやすいか意識して、保守しやすいソースコードを目指しましょう。
株式会社ONE WEDGE
【Serverlessで世の中をもっと楽しく】 ONE WEDGEはServerlessシステム開発を中核技術としてWeb系システム開発、AWS/GCPを利用した業務システム・サービス開発、PWAを用いたモバイル開発、Alexaスキル開発など、元気と技術力を武器にお客様に真摯に向き合う価値創造企業です。
Discussion