sinProject流システム開発のススメ #003 コメントは最小限に

前回:sinProject流システム開発のススメ #002 同じ処理を「書かない・書かせない・ゆるさない」

コメントは最小限にします。書くのは

  • TODOなどの「タスクコメント」
  • Javadocなどの「ドキュメンテーションコメント」

この2種類だけです。

※タスクコメントとは「TODO:」や「MEMO:」「DEBUG:」などと一緒に記述するタスク(やること)を管理するためのコメントです。
※ドキュメンテーションコメントとはクラスやメソッドの説明を行うコメントです。APIドキュメントなどを作成するときにこのコメントが使われます。

処理の流れを説明するようなコメントが書きたくなった時、書かないと分からないような処理があるときは、そのブロックをメソッド化します。メソッド化してそのメソッドのドキュメンテーションコメントに説明を書きます。

またメソッド名は「動詞から始める英語表記」で何をするメソッドかわかるような名前にします。メソッド名に加え変数名も省略などをせずに見てすぐに理解できる名前にします。メソッド名や変数名の話はまた後ほどしたいと思います。

コンピューターが理解できない書き方は開発環境が指摘してくれますが、人間に読みにくいかどうかまで開発環境は指摘してくれません。でもプログラムは未来の自分や他人が見てもすぐに理解できる、そういったコードが「良いコード」です。難しい書き方や誰も理解できないようなアルゴリズムを書くことより「すごい読みやすくて分かりやすい」と言われるコードを目指します。

では、前回のcalcメソッドにドキュメンテーションコメントを書いてみます。また calcメソッドの中で戻り値用の変数「result」を準備しました。

[code lang=”java”] package net.sinproject;

public class Lesson {

/**
* 値を2倍して1を足します。
* @param value もとの値
* @return 計算結果
*/
public static int calc(int value) {
int result = value * 2 + 1;

return result;
}

// …
}
[/code]

Javaの開発環境(Eclipseなど)の場合、メソッドやクラスの一つ上の行で「/**」と入力してエンターキーを押すとドキュメンテーションコメントのひな形が生成されます(C#の場合は「///」でできます)。ドキュメンテーションコメントには、そのメソッドは何をするか、引数の説明、戻り値の説明などを書きます。

戻り値を格納するための変数名は「result」とします。また、return文の前にはコードを見やすくするために空行を入れます。今回は request 変数の宣言、代入の後に処理が return しかありませんが、変数宣言の後も必ず空行を入れるようにします。

今回は短いですがおさらいをしておきます。

  • コメントは「タスクコメント」と「ドキュメンテーションコメント」だけ書く。それ以外は書かない。
  • コメントを書きたくなるような処理は、処理ブロックをメソッド化する。
  • 人間が読みやすいコードが「良いコード」である。
  • 戻り値を格納する変数名は「result」とする。
  • return 行の前に空行を入れる。
  • 変数の宣言部の後に1行空行を入れる。

次回:sinProject流システム開発のススメ #004 早めのreturn

Leave a comment

メールアドレスが公開されることはありません。

*

日本語が含まれない投稿は無視されますのでご注意ください。(スパム対策)