Java コメント

コメントはプログラムの実行されない部分です。コンパイラは、コメントを意図していないため、単純に無視します。これらは「人間の」言語で書かれており、開発者や開発に携わる人々にプログラム、プログラムの一部、一行やメソッドを説明することを目的としています。ほとんどの場合、コメントは英語で書かれますが、これは一種の伝統です。この記事では、Java のコメントと、それを正しく使用してあなたとあなたのチームメイトの作業を楽にする方法について説明します。

Java コメント: 重要な理由

彼らは、プログラマは自分のコードにコメントすることに関して非常に怠け者だと言います。ただし、これは非常に重要なスキルなので、Java を学び始めたばかりであっても、過小評価しないでください。適切にコメントされたコードは、コメントのないコードよりもはるかに価値が高くなります。そのようなプログラムは保守がはるかに簡単であるためです。大規模なプロジェクトはほとんどの場合 Java で記述されるため、プログラマが他の人のコードを扱うのが容易になるため、有能なコメントによって開発がスピードアップされます。コメントは次の目的で必要です。

• コードを理解します。あなたのもの、または他の人のもの。自分で書いたコードなので解読する必要がないと思われる場合は、1 か月前かそれより前に書いた比較的複雑なプログラムを開いて、何を、どこで、なぜ念頭に置いていたのかをすぐに理解してみてください。コメントを使用すると、プログラムまたはプログラムのブロックのロジックを説明したり、後でコードを操作する人に推奨事項を残したりすることができます。このタイプのコメントは説明的であると言えます。

• オブジェクトの目的、入力パラメータと出力パラメータ (存在する場合)、開発者に関するデータ、およびコード フラグメントに関連するその他の重要なものに関する情報が含まれます。このようなコメントは、モジュール、ライブラリ、プロシージャ、関数のヘッダーにあります。これらはドキュメントコメントと呼ぶことができます。

• バグを制御し、コードを改善します。問題のあるコードや改善が必要なコードはいつでもコメントアウトして、後で再検討することができます。特定の問題を別の方法で解決できるが、時間がない場合は、そのアイデアをコメントに書いてください。そうしないと、新しいコードのプレッシャーにさらされて、そのことを忘れてしまう可能性が高くなります。

Javaのコメントの種類

コメントには何でも書き込めるにもかかわらず、Java には特定の種類のコメントとその使用に関するルールがあります。Java コメントのコールドでは次のようになります。

• 一行コメント
• 複数行のコメント
• ドキュメントのコメント

一行コメント

最も一般的な Java コメントは単一行のコメントです。このようなコメントを示すには、テキスト//の前に二重スラッシュを入れるだけで十分です。単一行のコメントには、コメントの先頭にのみフラグが立てられます。コメントは行末まで続きます。構文：

//here is a single line comment.

このタイプの Java コメントの例を見てみましょう。

public class CommentsDemo1 {
   public static void main(String[] args) {
       System.out.println("This text is visible for Java compiler");
       //this text is single line comment
//This one is also single line comment
//they both (and me) are invisible for compiler
   }
}

出力は次のとおりです。 通常、単一行のコメントは、プログラム内のコメントされた場所の上または下に配置されますが、場合によっては同じ行に配置されます。コメントが何を指しているかが視覚的に明確であることが重要です。

複数行のコメント

Java コメントを書くのに 1 行では足りない場合があります。たとえば、メソッドがどのように機能するか、実装している複雑な式を説明する必要があります。この場合、複数の単一行コメントを記述することもできますが、いわゆる複数行コメントを記述する方が合理的です。両側に/* */という記号が付いています。複数行のコメントの構文:

/*This comment
is
Multi line comment
we can describe here
what we need */

コード内の複数行のコメントの例を見てみましょう

public class RleTest {

   /*
   Run Length Encoding (RLE),  a data compression algorithm
   that replaces repeated characters (series)
   with one character and the number of its repetitions.

   this method is to decode a String using run-length encoding

    */
   private static String decodeRle(String encoded) {
       if (encoded.isBlank()) return "";
       StringBuilder result = new StringBuilder();
       int count = 0;
       char baseChar = encoded.charAt(0);
       for (int i = 1; i <= encoded.length(); i++) {
           char c = i == encoded.length() ? '$' : encoded.charAt(i);
           if (Character.isDigit(c)) {
               count = count * 10 + Character.digit(c, 10);
           } else {
               do {
                   result.append(baseChar);
                   count--;
               } while (count > 0);
               count = 0;
               baseChar = c;
           }
       }
       return result.toString();
   }
   public static void main(String[] args) {
       System.out.println(decodeRle("C3ecddf8"));
   }
}

Java ドキュメントのコメント

これは、ドキュメント ページの生成に使用される特別なタイプの Java コメントです。通常、開発者は、Java ソース コードから HTML 形式で API ドキュメントを生成するドキュメント ジェネレーターである Javadoc を使用してドキュメント コメントを作成します。Javadoc で使用されるドキュメントの形式は、Java クラスをドキュメント化するための業界標準であり、IntelliJ IDEA や Eclipse などの最も一般的な IDE は Javadoc HTML を自動的に生成します。Java ドキュメントのコメントの構文は次のとおりです。

/**
Some important Javadoc comments here
You don’t know it yet, but Javadoc rulez

@author  Java Developer
*/

以下に例を示します。これは Java Shortクラスのフラグメントです。ちなみに、IDE から任意の Java クラス コードを確認できます (たとえば、Windows からの IntelliJ IDEA では、任意のクラス名またはメソッド名で ctrl+LBM または ctrl+b (Windows の場合) を押すだけです)。

package java.lang;

import jdk.internal.HotSpotIntrinsicCandidate;
import jdk.internal.misc.VM;

/**
* The {@code Short} class wraps a value of primitive type {@code
* short} in an object.  An object of type {@code Short} contains a
* single field whose type is {@code short}.
*
* <p>In addition, this class provides several methods for converting
* a {@code short} to a {@code String} and a {@code String} to a
* {@code short}, as well as other constants and methods useful when
* dealing with a {@code short}.
*
* @author  Nakul Saraiya
* @author  Joseph D. Darcy
* @see     java.lang.Number
* @since   1.1
*/
public final class Short extends Number implements Comparable<Short> {

   /**
    * A constant holding the minimum value a {@code short} can
    * have, -2<sup>15</sup>.
    */
   public static final short   MIN_VALUE = -32768;

   /**
    * A constant holding the maximum value a {@code short} can
    * have, 2<sup>15</sup>-1.
    */
   public static final short   MAX_VALUE = 32767;

   /**
    * The {@code Class} instance representing the primitive type
    * {@code short}.
    */
   @SuppressWarnings("unchecked")

以下は、よく知られ、すべての初心者に愛されているprintln()メソッドの Java コードであり、次のようなコメントが付いています。

/**
* Prints a String and then terminate the line.  This method behaves as
* though it invokes {@link #print(String)} and then
* {@link #println()}.
*
* @param x  The {@code String} to be printed.
*/
public void println(String x) {
   if (getClass() == PrintStream.class) {
       writeln(String.valueOf(x));
   } else {
       synchronized (this) {
           print(x);
           newLine();
       }
   }
}

Javadoc には、上記のコードに見られるように、@ でマークされた特別な Javadoc タグがいくつかあります。このような Javadoc タグの例は、クラス作成者の名前を追加する @author です。もう 1 つの Javadoc タグは @since で、このクラスが指定されたバージョンの Java 以降に使用されていることを示すコメントを追加します。優れた Javadoc ドキュメントを作成するには、知識と経験 (そして忍耐!) が必要です。Javadoc の詳細については、公式ドキュメント「How to Write Doc Comments for the Javadoc Tool」を参照 してください。

PS：実生活からの面白いコメントの例

/**
*Dear Maintainer
*
*Once you are done trying to 'optimize' this routine,
*and you have realized what a terrible mistake that was,
*please increment the following counter as a warning
*to the next guy.
*
*total_hours_wasted_here = 73
*/

Exception up = new Exception("Something is really wrong.");
throw up;  //ha ha

// When I wrote this, only God and I understood what I was doing
// Now, God only knows

// sometimes I believe compiler ignores all my comments

/**
Always returns true.
*/
public boolean isAvailable() {
return false;
}

学んだことをさらに強化するには、Java コースのビデオ レッスンを視聴することをお勧めします。