| English | 意味 |
|---|---|
| comment/ˈkɒment/ | コメント |
コメントはavesな数式を修正しない
- 価格が 100 の場合、
total = price * 10 / 100;は コメント が「10%割引後の支払額」と書いていても 10 を計算します。その説明を編集しても、式は 90 を計算するようにはなりません。 - この整数例で意図した支払い額を計算するためには、avesな式を
price * 90 / 100に変更してください。コメントは意図されたポリシーを示すことがありますので、コードが実際にそれを実装しているか確認してください。
コードから除外されるテキストを特定する
//は改行まで続くコメントを開始します。/*は次の*/まで続くブロックコメントを開始し、ブロックコメントはネストできません。文字列リテラル内の区切り記号はテキストであるため、"https://example.com"はコメントを開始しません。- コメント本文はJavaステートメントとして実行されません。別の解説を追加してもavesな式は変わらず、
//をavesな代入文の前に配置すると、コンパイル済みのコードからその代入文が削除され、動作が変わることがあります。
Javadocタグを別行に配置する
- 宣言の直前にある
/** ... */のドキュメントコメントはJavadocによって処理されます。その要約は操作を説明し、@paramや@returnなどのブロックタグは任意の空白と*の後に独自の行から始まります。 - 以下の完全なクラスは非負の半径をドキュメント化し、円の面積を返します。タグは入力、出力および拒絶された入力を説明しますが、コメントだけでは事前条件を強制できないため、メソッドは明示的に負の半径をチェックします。
/** Circle-area calculations for finite radii. */
public class AreaDoc {
/**
* Returns the area of a circle for a finite radius.
* @param r the non-negative radius
* @return the area in squared radius units
* @throws IllegalArgumentException if r is negative
*/
public static double area(double r) {
if (r < 0) {
throw new IllegalArgumentException("Negative radius");
}
return Math.PI * r * r;
}
}
Javadocは、同じ行の要旨テキストの後に埋め込まれた@paramをブロックタグとして認識します。
難易度 1/5 · 100 コイン + 今日初回完了時に小ボーナス付与
ブロックタグは、任意の空白と任意の先頭のアスタリスクの後に新しい行で始まります。表示されている多行コメントを使用してください。
読者が見えない決定を説明する
- 有用な割引に関するコメントは「支払額は表示価格の 90% です；この演習では整数単価を使用しています」と記載できます。これはポリシーと仮定を説明しますが、
// multiply by 90は単なる操作の繰り返しに過ぎません。 - パブリックメソッドの要約は、本体が短い場合でも有用です。呼び出し者は実装を研究せずに契約を知る必要があります。すべての記述的コメントが冗長であると宣言するよりも、欠落している文脈を提供する説明を優先してください。
Javaプログラムが実行される際、コメントは...
難易度 1/5 · 100 コイン + 今日初回完了時に小ボーナス付与
コメントは人間用であり — Javaは無視する。
Javaで単行コメントを開始するのはどれか？
難易度 1/5 · 100 コイン + 今日初回完了時に小ボーナス付与
// は行の終端まで続きます；/* */ はブロックである。
どのコメントスタイルがツールによってAPIドキュメントに変換されますか？
難易度 1/5 · 100 コイン + 今日初回完了時に小ボーナス付与
Javadoc /** */ に @param/@return を含めばAPIドキュメントを生成する。
未変更のアクティブな数式の横に解説コメントを追加すると、計算が修復されます。
難易度 1/5 · 100 コイン + 今日初回完了時に小ボーナス付与
False: 解説コメントはステートメントではありません。ステートメントを無効化（コメントアウト）すると動作が変わりますが、これはどのコードが有効になるかを変えることになり、数式自体の値は変わりません。
良いコメントは「なぜ」を説明し、コードが自明に行っていることを述べるものではない。
難易度 1/5 · 100 コイン + 今日初回完了時に小ボーナス付与
自明なことを説明するのではなく、意図をコメントせよ。
実装に対するドキュメントを確認する
- コメントが負の半径を拒絶することを約束しているにもかかわらず、ガードが削除されたと仮定します。ドキュメントは正常に生成され continued としても、今や誤りとなります。通常の半径だけでなく、負の入力についてもテストしてください。
- 振る舞いが変更されたら、実装、検証、およびドキュメントを同時に更新すること。APIページの生成は、すべての主張の真偽を検証するのではなく、ドキュメントの構文のみを確認する。
/** Returns an area. @param r radius @return area */ はブロックタグを行の先頭に配置しません。上記のマルチライン形式を使用し、生成されたパラメータとリターンセクションを確認してください。通常の解説コメントは実行可能な修正にはなりません。
有用なコメントか否か？
良いコメントは意図を説明し、自明なことを説明するものではない。それぞれを分類せよ。
削除された代入文を予測する
int x = 1;から始めます。x = 5;が有効な場合、x を出力すると 5 になります；その行を// x = 5;に置き換えると 1 が出力されます。どのステートメントが有効かを変更することは、変更していないステートメントの横にメモを追加することとは異なります。- 3つの質問を別々に確認します：有効な計算は正しいか、コメントがそれを正確に説明しているか、Javadocタグが意図したセクションに正しくパースされているかです。コンパイルが成功したからといって、これら3つすべてに回答できるわけではありません。
コメントはコードを読者に説明するためのものです。区切り文字はステートメントを除外できますが、有効なコードの横にあるメモは計算を修正しません。Javadocブロックタグはそれぞれ別の行で始まり、ドキュメント化された契約は実装と一致させる必要があります。
For a price of 100, type the amount paid after a ten percent discount.
難易度 1/5 · 100 コイン + 今日初回完了時に小ボーナス付与
The intended payment is 100−10=90. The misleading comment does not make the original expression calculate 90.
int x = 1; の次に別行に // x = 5; が続いています。xに出力される値は何ですか？
難易度 2/5 · 140 コイン + 今日初回完了時に小ボーナス付与
5への代入は単行コメントによって除外されるため、xは1のままです。