Commenti Java

I commenti sono la parte di un programma che non viene eseguita. Il compilatore ignora semplicemente i commenti perché non sono destinati a questo scopo. Sono scritti in linguaggio “umano” e hanno lo scopo di spiegare il programma, parte del programma, una singola riga o metodo per gli sviluppatori o le persone coinvolte nello sviluppo. Molto spesso i commenti sono scritti in inglese, è una specie di tradizione. In questo articolo parleremo dei commenti in Java e di come utilizzarli correttamente per semplificare la vita a te e ai tuoi compagni di squadra.

Commenti Java: perché sono importanti

Dicono che i programmatori siano estremamente pigri quando si tratta di commentare il proprio codice. Tuttavia, questa è un'abilità molto importante, quindi non sottovalutarla, anche se hai appena iniziato a imparare Java. Il codice ben commentato è molto più prezioso del codice senza commenti perché un programma di questo tipo è molto più semplice da mantenere. Poiché i progetti di grandi dimensioni sono spesso scritti in Java, i commenti competenti accelerano anche lo sviluppo, poiché è più facile per un programmatore gestire il codice di altre persone. I commenti sono necessari per:

• Comprendere il codice. Il tuo o quello di qualcun altro. Se ti sembra di non aver bisogno di decifrare il tuo codice perché lo hai scritto tu, prova ad aprire un programma relativamente complesso che hai scritto un mese fa o anche prima e capisci rapidamente cosa, dove e perché avevi in ​​mente. I commenti possono essere utilizzati per spiegare la logica di un programma o di un blocco di programma, nonché per lasciare consigli a coloro che lavoreranno con il codice in seguito. Questo tipo di commento può essere definito esplicativo.

• Contenente informazioni sullo scopo degli oggetti, parametri di input e output (se presenti), dati sullo sviluppatore e altri elementi importanti relativi al frammento di codice. Tali commenti si trovano nelle intestazioni di moduli, librerie, procedure e funzioni. Possono essere chiamati commenti di documentazione.

• Controlla i bug e migliora il codice. Il codice discutibile o il codice che necessita di miglioramenti può sempre essere commentato e rivisitato in seguito. Se ti viene in mente che un certo problema può essere risolto in modo diverso, ma ora non hai tempo per farlo, scrivi questa idea nel commento. Altrimenti, molto probabilmente, sotto la pressione del nuovo codice, te ne dimenticherai.

Tipi di commenti in Java

Nonostante sia possibile scrivere di tutto nei commenti, in Java esistono alcuni tipi di commenti e regole per utilizzarli. Nei commenti Java potrebbe essere:

• Commenti a riga singola
• Commenti su più righe
• Commenti sulla documentazione

Commenti a riga singola

I commenti Java più comuni sono commenti a riga singola. Per indicare un commento di questo tipo è sufficiente mettere una doppia barra prima del testo // . I commenti a riga singola vengono contrassegnati solo all'inizio del commento. Il commento continua fino alla fine della riga. Sintassi:

//here is a single line comment.

Facciamo un esempio di questo tipo di commenti 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
   }
}

L'output è: Di solito un commento su una sola riga si trova sopra o sotto la posizione commentata nel programma, occasionalmente sulla stessa riga. È importante che sia visivamente chiaro a cosa si riferisce il commento.

Commenti su più righe

A volte non c'è abbastanza una riga per scrivere un commento Java. Ad esempio, devi descrivere come funziona un metodo o una formula complessa che stai implementando. In questo caso è possibile scrivere più commenti su una riga, ma sarebbe più razionale scrivere i cosiddetti commenti su più righe. Sono contrassegnati su entrambi i lati con i simboli /* */ . Sintassi dei commenti su più righe:

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

Facciamo un esempio di commenti su più righe nel codice

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"));
   }
}

Commenti sulla documentazione Java

Questo è un tipo speciale di commenti Java utilizzati per generare una pagina di documentazione. Di solito gli sviluppatori scrivono commenti sulla documentazione utilizzando Javadoc, un generatore di documentazione per generare documentazione API in formato HTML dal codice sorgente Java. Il formato dei documenti utilizzato da Javadoc è lo standard del settore per la documentazione delle classi Java e gli IDE più popolari come IntelliJ IDEA ed Eclipse generano automaticamente Javadoc HTML. I commenti della documentazione Java hanno la sintassi seguente:

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

@author  Java Developer
*/

Ecco un esempio: è un frammento della classe Java Short . A proposito, puoi guardare qualsiasi codice di classe Java dal tuo IDE (ad esempio in IntelliJ IDEA da Windows basta premere ctrl+LBM o ctrl + b (in Windows) sul nome di qualsiasi classe o metodo).

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")

Ecco il codice Java del metodo println() noto e amato da tutti i principianti con tale commento:

/**
* 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 ha alcuni tag Javadoc speciali contrassegnati con @ che puoi vedere nel codice sopra. L'esempio di tale tag Javadoc è @author che aggiunge il nome dell'autore della classe. Un altro tag Javadoc è @since aggiunge un commento che indica che questa classe viene utilizzata a partire dalla versione specificata di Java. Scrivere buoni documenti Javadoc richiede conoscenza ed esperienza (e pazienza!). Puoi trovare maggiori informazioni su Javadoc nella documentazione ufficiale How to Write Doc Comments for the Javadoc Tool .

PS alcuni esempi di commenti divertenti dalla vita reale

/**
*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;
}

Per rafforzare ciò che hai imparato, ti suggeriamo di guardare una lezione video dal nostro corso Java