Java >> Java tutorial >  >> Java

Kommentarer i Java

Java

Enhver software ville være ufuldstændig uden kommentarer. De hjælper den person, der ser koden (normalt dig), med at forstå programmets formål og funktionalitet. Du skal udvikle praksis med altid at kommentere din kode, mens du skriver den i stedet for bagefter.

De værktøjer, vi vil bruge i denne artikel, vil minde dig om at skrive kommentarer, hjælpe dig med at skrive dem og udnytte de kommentarer, du har skrevet, til at gøre programmering lettere. Benyt venligst dem.

Typer af kommentarer i Java

Der er fire til fem typer kommentarer i Java, afhængigt af hvordan du ser ud. Disse omfatter:

Dokumentations- og implementeringskommentarer

Dokumentationskommentarer og implementeringskommentarer er de to slags kommentarer, der bør forekomme i programmer. Klassens, feltets eller metodens semantik er beskrevet i dokumentationskommentarer.

Du bør være i stand til at bruge klassen og dens metoder uden at læse nogen kildekode, hvis dokumentationskommentarerne er gode. På den anden side forklarer implementeringskommentarer, hvordan et stykke kode fungerer. Selvom du bør skrive implementeringskommentarer efter behov, er dokumentationskommentarer en vigtig programmeringskomponent og kræves her.

De andre typer kommentarer i Java inkluderer:

Kommentarer på en enkelt linje

To skråstreger frem (//) begynder kommentarer på en enkelt linje. Java ignorerer enhver tekst mellem // og slutningen af ​​linjen (vil ikke blive udført). Før hver kodelinje bruges en enkeltlinjekommentar:

// This is a comment
System.out.println("Single line comments in Java");

En enkeltlinjekommentar bruges i slutningen af ​​en kodelinje i følgende eksempel:

System.out.println("Single Line Comments at the end of the line"); // This is a comment

Multi-line kommentarer i Java

Kommentarer, der spænder over flere linjer, begynder med /* og slutter med */. Java vil ignorere enhver tekst mellem /* og */. For at tydeliggøre koden bruger dette eksempel en flerlinjet bemærkning (en kommentarblok):

/* The output of the code below is the words Hello multi-line comments in Java

to the screen, and it is code magic */

System.out.println("Hello multi-line comments in java");

Ønsker du kommentarer på én eller flere linier?

Det er helt op til dig, hvilken metode du ønsker at bruge.// bruges til korte kommentarer, og /* */ bruges til længere.

Hvad er fordelene ved at bruge kommentarer i kode?

  • Kommentarer tilføjer detaljer til koden for at gøre programmet mere læseligt.
  • Det gør det nemt at vedligeholde koden og lokalisere fejl.
  • Kommentarerne giver flere oplysninger eller forklaringer om en variabel, metode, klasse eller sætning.
  • Det kan også forhindre udførelse af programkode, mens alternativ kode evalueres.

Kommentarer til Java-dokumentation

Dokumentationskommentarer bruges almindeligvis til at hjælpe med at konstruere dokumentations-API, når du skriver massive programmer til et projekt eller en softwareapplikation. Disse API'er er nødvendige til reference for at bestemme, hvilke klasser, metoder, argumenter og andre elementer der bruges i koden.

Javadoc-værktøjet er påkrævet for at udvikle dokumentations-API. Mellem /** og */ er dokumentationskommentarerne.

Syntaksen er som følger:

/**  
*
*several tags to depict the parameter
*or heading or author-name
*We can also use HTML tags   
*
*/

Tags til Javadoc

Tags, der ofte bruges i dokumentationskommentarer, omfatter:

Tag Syntaks Beskrivelse
{@docRoot} {@docRoot} skildrer den relative sti til rodbiblioteket for det resulterende dokument genereret fra en hvilken som helst side.
@forfatter @forfatternavn teksten tilføjer klassens forfatter.
@code {@kodetekst viser teksten i kodeskrifttype, selvom den ikke fortolker den som hverken indlejret javadoc-tag eller html-markering.
@version @version version-tekst angiver "Version"-underoverskriften og version-teksten, når du bruger versionsindstillingen.
@siden @siden udgivelsen tilføjer "Siden"-overskriften med siden-tekst til den resulterende dokumentation, der er genereret.
@param @param parameternavnbeskrivelsen tilføjer en parameter med et navn og en beskrivelse til afsnittet kaldet 'Parameters'.
@return @return beskrivelse Det er nødvendigt for enhver metode, der returnerer noget undtagen void.

Afsnittet nedenfor giver os mulighed for at bruge Javadoc-tagget i et Java-program.

 import java.io.*;  
      
    /**
     * <h2> Number Calculation </h2>
     * This program is an application implemention
     * to perform operation such as addition of numbers  
     * and print the result  
     * <p>
     * <b>Note:</b> Comments are responsible for making the code readable and  
     * easy to understand.
     *  
     * @author Codeunderscored  
     * @version 16.0
     * @since 2022-03-19
     */  
       
     public class CodeCalculation{  
        /**
         * The code in this method here sums two integers.
         * @param input1 This is the first parameter to sum() method
         * @param input2 This is the second parameter to the sum() method.
         * @return int This returns the addition of input1 and input2
         */  
        public int sum(int input1, int input2){  
            return input1 + input2;  
        }  
        /**
        * This is the primary method uses of sum() method.
        * @param args Unused
        * @see IOException  
        */    
        public static void main(String[] args) {  
            Calculate obj = new Calculate();  
            int result = obj.sum(25, 35);  
      
            System.out.println("Number summation: " + result);  
        }    
     }

HTML-filerne til Calculate-klassen oprettes nu i den aktuelle mappe, abcDemo. Vi kan se dokumentationsbemærkningen, der forklarer Calculate-klassen, når vi åbner HTML-filerne.

Stil

Dokumentationskommentarer i Java sættes inde i kommentarafgrænsningerne /**… */ efter konvention, med én kommentar pr. klasse, grænseflade eller medlem. Hver kommentarlinje skal begynde med et "*" og skal forekomme direkte før klassen, grænsefladen eller medlemserklæringen.

Her er en skør klasse, der viser, hvordan du formaterer dine kommentarer (ikke hvordan du skriver Java-kode):

/**

/**
 * The Codeunderscored class is an example to illustrate documentation
 * comments.
 */
public class Codeunderscored {

    /**
    * integer keeps track of for fun.
    */
    private int count;

    ...

    /**
    * Increment a value by delta and return the new value.
    *
    * @param  delta   the amount the value should be incremented by
    * @return         the post-incremented value
    */
   int increment(int delta) {
       ...
   }
}

Det er værd at bemærke, at kommentarerne alle er formateret på samme måde, med det foranstillede "/" indrykket til samme niveau som koden, der bemærkes på.

"@param" og "@return" tags er også inkluderet i metodekommentaren. Den viser navnene på alle parametre og metodens output. Hvis du skriver "/**" efter at have skrevet metodeerklæringen, genererer Eclipse disse automatisk for dig.

At inkludere sådanne kommentarer er en genial idé, da du vil være i stand til at se tilbage på din kode og bedre forstå den. Andre vil også være i stand til at forstå din kode bedre. Der er dog visse ekstra fordele ved at formatere dem på denne måde.

Du kan parse disse kommentarer med værktøjer til at levere dokumentation for din kode (deraf navnet dokumentationskommentarer). Javadoc-værktøjerne kan læse disse kommentarer, som vil generere HTML-lignende dokumentation. Eclipse kan også læse disse kommentarer. Ved at skrive et objektnavn efterfulgt af "." operatør, vil alle metoder, der leveres af det pågældende objekts klasse, blive vist.

Når du holder musen over et metodekald, vil du også se korrekt formateret dokumentation. Yderligere, når du tilføjer et nyt element til UML Lab, vil det bede dig om feedback. Hvis du gør det til en øvelse at skrive dem med det samme, behøver du ikke at gøre mere for at holde din kode godt kommenteret.

Oprettelse af websider ved hjælp af Javadoc

Det smukke ved Javadocs er, at Java-systemet forstår, hvordan man læser alle Java-elementers kommentarer og transformerer dem til standardiserede, velformaterede og letlæselige websider.

I Eclipse er alt, der kræves, at opnå følgende:

  • Højreklik på det ønskede projekt i Pakkestifinder.
  • Klik på Næste efter at have valgt Eksporter.../Javadoc.
  • “Javadoc-kommandoen” er muligvis ikke indstillet, første gang du genererer Javadocs.
  • Hvis det ikke allerede er indstillet, skal du klikke på knappen Konfigurer og navigere til Java JDK-installationsmappen, hvor javadoc.exe-filen er placeret.
  • Den komplette kildekode vil blive valgt som standard.
  • Fjern markeringen af ​​alle pakker, du ikke ønsker, at dokumentation skal genereres, hvis det ønskes.
  • Vælg "Privat" for det producerede synlighedsniveau.
  • Alle tilgængelige Javadocs vil blive genereret som et resultat af dette.
  • Vælg "standard doclet"-browseren til din dokumentations destinationsmappe.
  • Det er normalt en "doc"-mappe direkte under projektets rod.
  • Vælg derefter Næste.
  • Klik på Udfør efter at have indtastet en relevant dokumenttitel.

For hvert af følgende skal du skrive dokumentationskommentarer:

  • Grænseflader og klasser
  • Alle inputparametre og returværdier
  • Metoder
  • Felter

Eclipse vil bruge dine kommentarer til at gøre dit liv lettere, så du vil opleve fordelene med det samme.

Alle autogenererede felter og metoder, såsom dem, der er lavet af dit GUI-skabende værktøj, skal også kommenteres. Disse omfatter WindowBuilder eller en anden kodegenerator, såsom UML Lab. Sidstnævnte vil give Eclipse mulighed for at vise dig, hvad hver variabel gør, og forbedre din evne til at forstå koden betydeligt i fremtiden. Selvom det ekstra arbejde kan se trættende ud, vil fordelene overgå indsatsen. At kommentere ting er altid en god idé.

Interne "//"-kommentarer anbefales stærkt til at dokumentere, hvad din kode forsøger at opnå. Det vil spare dig for timers fejlfindingstid, hvis du glemmer, hvad en funktion skal udrette!

Husk at kommentere enhver autogenereret metode, hvor du har skrevet kode i metodeteksten, såsom en knap-klik-lytters handlingUdført funktion, for at beskrive adfærden af ​​din kode!

Dokumentation af tilsidesatte metoder

Selvom det kan være fristende at springe over at dokumentere tilsidesættende metoder (dem, der er markeret med annotationen "@Override"), er dette kun berettiget, hvis den implementerende enheds dokumentation ikke vil bidrage med noget til den dokumentation, der leveres af metodens abstrakte beskrivelse. Men fordi enhver implementering af en abstrakt metode adskiller sig på en eller anden måde, er denne omstændighed relativt standard.

Det er afgørende at dokumentere sådanne skel, så brugere af disse metoder kender variationerne mellem en implementering og den næste.

Desværre erstatter tilføjelse af Javadocs til en tilsidesat metode dokumentationen af, at den abstrakte metode tilsidesættes fuldstændigt. Fordi den abstrakte beskrivelse stadig er relevant, er det en god idé at inkludere den i implementeringsprocessens opdaterede dokumentation. Ved at bruge "{@inheritDoc}"-tagget er dette nemt at opnå:

/**
	 * {@inheritDoc}
	 * This inserts the docs from the overridden method above.
	 * Implementation-specific docuementation can then be added here.
*/
@Override
public void codeMethod() {

}

Tips til oprettelse af Javadocs

Autogenerer @param og @return

Du skal blot indtaste "/**Enter>" før en metode eller klasse i Eclipse vil generere alle de nødvendige @param og @return attributter.

Advarsler om "selvlukkende elementer ikke tilladt" vises ikke længere

Javadoc-compilatoren i Java 8 JDK følger HTML 4.01-standarder, som tillader "void element"-tags (tags uden omsluttende indhold) som br og image at blive skrevet uden det afsluttende "/", som i den mere regulariserede HTML 5-standard:

  • HTML 4.01:
    ,
  • HTML 5:
    ,

På grund af denne overholdelse af den tidligere HTML-standard, hvis der stødes på et HTML 5-struktureret ugyldigt element-tag, sender Javadoc som standard en advarsel om "selvlukkende element ikke tilladt". For at forhindre Javadoc i at vise denne advarsel, skal du bruge følgende kommandolinjeparameter:

  • -Xdoclint:all,-html

HTML "lint"-stilkontrollen er deaktiveret på grund af dette. Desværre er Javadoc-dokumentationen tavs om, hvad denne indstilling deaktiverer andre stiltjek.

Når du udfører en eksport/Javadoc-handling i Eclipse, kan du angive denne mulighed ved at skrive ovenstående mulighed (inklusive det indledende "-"-symbol) i boksen "Ekstra Javadoc-indstillinger" i dialogpanelet "Konfigurer Javadoc-argumenter", når den vises.

Indstil compileren til at give dig besked, hvis du ikke har nogen Javadocs

Indstil compileren til at advare eller udsende fejl på manglende eller misdannede Javadocs i Eclipse's Preferences/Java/Compiler/Javadoc. Det er en fantastisk måde at sikre, at din kode er korrekt dokumenteret!

Del dine Javadocs med andre, hvis du vil

Javadocs, der genereres, er simpelthen HTML-websider. Ulempen er, at du skal bruge en webserver til at dele dem med andre.

Heldigvis giver Rice en ligetil metode til at vise websider fra dit "U:drive":

  • https://kb.rice.edu/page.php?id=70749 Hosting af et personligt websted
  • https://kb.rice.edu/search.php?q=mount+drive&cat=0 Montering af dit U:-drev

Alt du skal gøre er at kopiere dine Javadocs til en mappe under U:/Public/www, og de kan ses i enhver browser. For mere information om, hvem du skal kontakte for at bestemme den præcise URL på dine Javadocs, se publikationerne nævnt ovenfor.

Eksempel:Program til illustration af de ofte brugte Comment tags i Java

/**
* <h1>Find average of three numbers!</h1>
* The FindAvg program implements an application that
* simply calculates the average of three integers and Prints
* the output on the screen.
*
* @author Codeunderscored
* @version 1.0
* @since 2017-02-18
*/
public class FindAvg
{
	/**
	* This method is used to find the average of three integers.
	* @param numA This is the first parameter to findAvg method
	* @param numB This is the second parameter to findAvg method
	* @param numC This is the second parameter to findAvg method
	* @return int This returns average of numA, numB and numC.
	*/
	public int findAvg(int numA, int numB, int numC)
	{
		return (numA + numB + numC)/3;
	}

	/**
	* This is the primary method that makes use of findAvg method.
	* @param args Unused.
	* @return Nothing.
	*/

	public static void main(String args[])
	{
		FindAvg obj = new FindAvg();
		int avg = obj.findAvg(10, 20, 30);

		System.out.println("Average of 10, 20 and 30 is :" + avg);
	}
}

Konklusion

Du kan bruge kommentarer til at forklare og forbedre læsbarheden af ​​Java-kode. Når man evaluerer alternativ kode, er den praktisk til at forhindre eksekvering.

Kommentarer i et program hjælper med at gøre det mere menneskeligt læsbart ved at sætte detaljerne i den involverede kode, og effektiv brug af kommentarer gør vedligeholdelse og fejlfinding nemmere. Når du kompilerer et program, ignorerer compileren kommentarer.

Den slags kommentarer i Java inkluderer:

  • Enkeltlinjekommentarer.
  • Kommentarer med flere linjer.
  • Dokumentationskommentarer.

For at illustrere kodefunktionaliteten bruger en nybegynder programmør generelt enkeltlinjekommentarer. Det er en af ​​de mest ligefremme kommentarer at skrive. Enkeltlinjekommentarer kan dog være kedelige at skrive, fordi vi skal tilbyde '//' ved hver linje for at beskrive en komplet metode i en kode eller et komplekst uddrag. For at komme uden om dette kan du bruge kommentarer på flere linjer.

Dokumentationskommentarerne bruges almindeligvis, når der skrives kode til et projekt/softwarepakke, fordi det hjælper med at generere en dokumentationsside til reference, som bruges til at lære om de tilgængelige metoder, deres parametre og så videre.


Java tag