Πώς να χρησιμοποιήσετε τα σχόλια στον κώδικα Java

Τα σχόλια Java είναι σημειώσεις σε ένα αρχείο κώδικα Java που αγνοούνται από τον μεταγλωττιστή και τον κινητήρα χρόνου εκτέλεσης. Χρησιμοποιούνται για να σχολιάσουν τον κώδικα, προκειμένου να διευκρινιστεί ο σχεδιασμός και ο σκοπός του. Μπορείτε να προσθέσετε έναν απεριόριστο αριθμό σχολίων σε ένα αρχείο Java, αλλά υπάρχουν κάποιες "βέλτιστες πρακτικές" που πρέπει να ακολουθήσετε όταν χρησιμοποιείτε σχόλια.

Γενικά, τα σχόλια κώδικα είναι σχόλια "εφαρμογής" που εξηγούν το πηγαίου κώδικα, όπως οι περιγραφές των κλάσεων, των διεπαφών, των μεθόδων και των πεδίων. Αυτά είναι συνήθως μερικές γραμμές που γράφονται πάνω ή δίπλα στον κώδικα Java για να διευκρινίσουν τι κάνει.

Ένας άλλος τύπος σχολίου Java είναι ένα σχόλιο Javadoc. Τα σχόλια Javadoc διαφέρουν ελαφρώς στη σύνταξη από τα σχόλια εφαρμογής και χρησιμοποιούνται από το πρόγραμμα javadoc.exe για τη δημιουργία τεκμηρίωσης Java HTML.

Είναι καλή πρακτική να έχετε τη συνήθεια να βάζετε σχόλια Java στον πηγαίο κώδικα σας για να βελτιώσετε την αναγνωσιμότητα και τη σαφήνεια για τον εαυτό σας και άλλους προγραμματιστές. Δεν είναι πάντα άμεσα σαφές τι εκτελείται μια ενότητα κώδικα Java. Μερικές επεξηγηματικές γραμμές μπορούν να μειώσουν δραστικά τον χρόνο που απαιτείται για να κατανοηθεί ο κώδικας.

Εφαρμογή σχολίων στο Κώδικα Java είναι μόνο εκεί για να διαβάζουν οι άνθρωποι. Οι μεταγλωττιστές της Java δεν τους νοιάζονται και πότε την κατάρτιση του προγράμματος, απλά παραλείπουν πάνω τους. Το μέγεθος και η αποτελεσματικότητα του προγραμματισμένου προγράμματος σας δεν θα επηρεαστεί από τον αριθμό των σχολίων στον πηγαίο σας κώδικα.

Τα σχόλια εφαρμογής έχουν δύο διαφορετικές μορφές:

• Σχόλια γραμμής: Για σχόλιο μιας γραμμής, πληκτρολογήστε "//" και ακολουθήστε τις δύο εμπρόσθιες περικοπές με το σχόλιό σας. Για παράδειγμα:

   // αυτό είναι ένα σχόλιο μιας γραμμής
  int guessNumber = (int) (Math.random () * 10); 

  Όταν ο μεταγλωττιστής συναντά τις δύο εμπρόσθιες εγκοπές, ξέρει ότι τα πάντα στα δεξιά τους πρέπει να θεωρηθούν ως σχόλιο. Αυτό είναι χρήσιμο όταν σφαλίζετε ένα κομμάτι κώδικα. Απλά προσθέστε ένα σχόλιο από μια γραμμή κώδικα που εντοπίζετε σφάλματα και ο μεταγλωττιστής δεν θα το δει:

  •  // αυτό είναι ένα σχόλιο μιας γραμμής
    // int guessNumber = (int) (Math.random () * 10). 

    Μπορείτε επίσης να χρησιμοποιήσετε τις δύο προς τα εμπρός λοξές γραμμές για να κάνετε ένα σχόλιο στο τέλος της γραμμής:

  •  // αυτό είναι ένα σχόλιο μιας γραμμής
    int guessNumber = (int) (Math.random () * 10); // Ένα σχόλιο στο τέλος της γραμμής 

• Αποκλεισμός σχολίων: Για να ξεκινήσετε ένα σχόλιο μπλοκ, πληκτρολογήστε "/ *". Τα πάντα μεταξύ της πλάγιας κάθετης και του αστερίσκου, ακόμα κι αν είναι σε διαφορετική γραμμή, αντιμετωπίζονται ως σχόλιο έως ότου οι χαρακτήρες "* /" τερματίσουν το σχόλιο. Για παράδειγμα:

   /* Αυτό 
  είναι 
  ένα
  ΟΙΚΟΔΟΜΙΚΟ ΤΕΤΡΑΓΩΝΟ
  σχόλιο
  */
  / * έτσι είναι αυτό * /
  

Χρησιμοποιήστε ειδικά σχόλια Javadoc για να τεκμηριώσετε το Java API σας. Το Javadoc είναι ένα εργαλείο που περιλαμβάνεται στο JDK που δημιουργεί τεκμηρίωση HTML από σχόλια στον πηγαίο κώδικα.

Ένα σχόλιο Javadoc στο

.Ιάβα

/**

*/

*

Τοποθετήστε αυτά τα σχόλια ακριβώς πάνω από τη μέθοδο, την κλάση, τον κατασκευαστή ή οποιοδήποτε άλλο στοιχείο Java που θέλετε να τεκμηριώσετε. Για παράδειγμα:

// myClass.java
/**
* Κάντε μια συνοπτική πρόταση που περιγράφει την τάξη σας.
* Εδώ είναι μια άλλη γραμμή.
*/
δημόσιοτάξη η τάξη μου
{
...
}

Το Javadoc ενσωματώνει διάφορες ετικέτες που ελέγχουν τον τρόπο δημιουργίας της τεκμηρίωσης. Για παράδειγμα, το

@param

 / ** κύρια μέθοδος
* @param args String []
*/​
δημόσιοστατικόςκενός main (συμβολοσειρά [] args)
​{
System.out.println ("Hello World!");
}

Πολλές άλλες ετικέτες είναι διαθέσιμες στο Javadoc και υποστηρίζει επίσης ετικέτες HTML για τον έλεγχο της παραγωγής. Ανατρέξτε στην τεκμηρίωση Java για περισσότερες λεπτομέρειες.

• Μην το σχολιάζετε. Δεν χρειάζεται να εξηγηθεί κάθε γραμμή του προγράμματος σας. Εάν το πρόγραμμά σας ρέει λογικά και δεν εμφανίζεται τίποτα απροσδόκητο, μην αισθάνεστε την ανάγκη να προσθέσετε ένα σχόλιο.
• Συμπληρώστε τα σχόλιά σας. Αν η γραμμή του κώδικα που σχολιάζετε είναι χαραγμένη, βεβαιωθείτε ότι το σχόλιό σας ταιριάζει με την εσοχή.
• Διατηρήστε σχόλια σχετικά. Μερικοί προγραμματιστές είναι εξαιρετικοί στον τροποποιητικό κώδικα, αλλά για κάποιο λόγο ξεχνούν να ενημερώσουν τα σχόλια. Εάν ένα σχόλιο δεν ισχύει πλέον, τότε είτε να το τροποποιήσετε ή να το καταργήσετε.
• Μην φωτίζετε τα σχόλια των μπλοκ. Τα παρακάτω θα οδηγήσουν σε σφάλμα μεταγλωττιστή:

   /* Αυτό 
  είναι
  / * Αυτό το σχόλιο ολοκληρώνει το πρώτο σχόλιο * /
  ένα
  ΟΙΚΟΔΟΜΙΚΟ ΤΕΤΡΑΓΩΝΟ
  σχόλιο
  */