Commenti in Java: non tutto è così semplice

introduzione

Commenti : sembrerebbe che potrebbe essere più semplice, e perché scrivere un intero articolo. Ma non è così semplice. Come ha detto il mio capo, chiunque può scrivere codice, ma scrivere un buon commento è difficile. La maggior parte dei corsi di lingua iniziano con il tradizionale Hello World. Anche nei Tutorial Oracle, nella sezione "Getting Started", iniziamo con "Hello World!" Applicazione . E fin dalle prime righe di codice li vediamo: commenti Java. La loro importanza è sottolineata anche dal fatto che in un documento così importante come la Convenzione sul codice Java, ai commenti viene assegnata una sezione separata: Commenti . Secondo la documentazione, i commenti in Java sono divisi in due tipi:

• commento sull'implementazione (o commento sul codice);
• commento documentativo.

I commenti al codice vengono utilizzati per descrivere singole righe/blocchi, mentre i commenti alla documentazione vengono utilizzati per descrivere le specifiche del codice (la sua interfaccia) indipendentemente dalla sua implementazione. I commenti Java vengono ignorati dal compilatore perché hanno senso per lo sviluppatore, non per l'utente. Pertanto è possibile ridurre la dimensione delle classi compilate.

Commenti sul codice Java

Dal nome è chiaro che questo commento si riferisce al codice e dovrebbe rispecchiarne le caratteristiche. I commenti al codice sono:

• Minuscolo (cioè descritto in una riga)

  // Строчный комментарий
  System.out.println("Hello, World!");




• Blocco (cioè vengono descritti come un blocco intero, perché non stanno in una riga)

  /*
   * Блочный комментарий
   */
  System.out.println("Hello");

Una caratteristica interessante di un commento di blocco è che se lo iniziamo con " /*- " (ovvero aggiungiamo un segno meno dopo l'asterisco), il testo di questo commento di blocco non verrà formattato. Interessante, ma con l'aiuto di alcuni commenti puoi dare alcuni suggerimenti sull'IDE. Ad esempio, utilizzando i commenti in linea " //@formatter:on " e " //@formatter:off " nell'IDE Eclipse è possibile disabilitare la formattazione per le sezioni di codice. È necessario utilizzare i commenti con parsimonia e solo dove necessario. Ad esempio, puoi leggere un articolo su questo argomento: "Non scrivere commenti sul codice!" . C'è un ottimo libro intitolato Clean Code: Creation, Analyzing, and Refactoring di Robert Martin. Ha un capitolo separato "Commenti". In epigrafe a questo capitolo, una citazione altrettanto eccellente: "Non commentare il codice errato: riscrivilo" di Brian W. Kernighan e P. J. Plower. Questo capitolo può essere trovato su Google Libri . Il significato generale può essere espresso in una sua citazione:

Ogni volta che commenti, sussulti e ti senti un fallimento."

È chiaro che non esiste una verità assoluta e talvolta i commenti sono necessari. Ma ci sono sempre delle opzioni e bisogna combattere i commenti inutili. Questo capitolo menziona anche commenti insoliti, TODO:

// TODO: Добавить World
System.out.println("Hello, ");

Il punto è che possono essere gestiti in modo speciale nell'IDE. Ad esempio in IDEA sono raccolti in una scheda separata, dove puoi visualizzarli: E un piccolo enigma con un commento: la riga “http://google.com” è una riga valida all'interno del metodo, perché http qui è in realtà un tag e quindi un commento. Spesso molti commenti possono andare da commenti sul codice a commenti sulla documentazione, di cui parleremo più avanti.

Commenti per la documentazione

I commenti sulla documentazione descrivono l'API pubblica. L'API è l'interfaccia di programmazione dell'applicazione, ovvero quelle classi e metodi disponibili ad altri sviluppatori per eseguire qualsiasi azione. In breve, questi commenti dovrebbero spiegare perché è stata creata questa o quella classe e pacchetto e cosa fa questo o quel metodo. Se necessario, puoi anche descrivere i campi della classe. Questo è esattamente ciò che vediamo nei tooltip dei nostri IDE, che vengono presentati come JavaDoc. Per esempio: Se approfondiamo questo metodo, possiamo vedere da dove proviene questo testo: Ancora una volta, vedere Java Code Convention: Convenzione del codice su come formattare correttamente un JavaDoc . Sono in qualche modo simili ai commenti di blocco, ma invece di un asterisco (non Asterix) ne vengono utilizzati due. Un esempio JavaDoc è stato fornito sopra. È inutile descrivere tutte le possibilità, poiché ciò è già scritto nella documentazione ufficiale di Oracle. Pertanto, esaminiamo tutto ciò di cui hai bisogno nella documentazione ufficiale JavaDoc , sezione "Descrizioni dei tag". Oracle ha anche un tutorial separato su questo argomento: How to Write Doc Comments for the Javadoc Tool . I suggerimenti nell'IDE sono carini, ma in realtà sono documenti per un motivo. Sulla base di questi commenti JavaDoc, viene generata la documentazione. Esiste un'utilità Javadoc speciale per questo . Come possiamo vedere, il Tutorial parla di questo. Una descrizione di come utilizzarlo si trova sul sito Web ufficiale Oracle per JavaDoc . Per vedere di persona come appare, puoi creare una sottodirectory nella directory con il nome del pacchetto, ad esempio: test . Crea una classe semplice con commenti al suo interno. Per esempio:

package test;

/**
 * This is a JavaDoc class comment
 */
public class JavaDocTest {

  /**
   * This is a JavaDoc public field comment
   */
  public static final String HELLO_MESSAGE = "Hello, World!";

  public static void main(String... args) {
    JavaDocTest.greetings();
  }

  /**
   * This is a JavaDoc public method comment
   */
  public static void greetings() {
    System.out.println(HELLO_MESSAGE);
  }
}

Successivamente, possiamo eseguire il seguente comando dalla directory che contiene la directory del nostro pacchetto: javadoc -d ./test test Successivamente, vedremo il processo di generazione della documentazione. E poi possiamo aprire index.html per vedere il documento generato. Vedrai spesso pubblicata la documentazione API. Ad esempio, l'API Spring Framework .

Conclusione

Come possiamo vedere, una cosa apparentemente semplice come i commenti si rivela in realtà molto più complicata. Pertanto, se dedichi un po' di tempo ai commenti e li segui, il tuo codice sarà migliore e sarai più prezioso come programmatore. #Viacheslav