Τεκμηριώστε τον κώδικα Java σας αυτόματα με το Javadoc

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

Η Java παρέχει βολικά μια ενσωματωμένη λύση στο πρόβλημα: Javadoc.

Το Javadoc μπορεί να σας βοηθήσει να τεκμηριώσετε τον κωδικό σας αυτόματα

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

Σίγουρα, ένας άλλος προγραμματιστής μπορεί να κοιτάξει τον κώδικά σας και να διαβάσει για τις συγκεκριμένες κλάσεις, μεθόδους και συναρτήσεις που έχει μπροστά του. Ωστόσο, είναι εξαιρετικά δύσκολο να αποκτήσετε μια καλή επισκόπηση όλου του κώδικα ή να βρείτε λειτουργίες που θα μπορούσαν να είναι χρήσιμες όταν δεν γνωρίζετε ότι υπάρχουν. Το Javadoc στοχεύει να λύσει αυτό το πρόβλημα.

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

Τι ακριβώς είναι το Javadoc και πώς λειτουργεί;

Το Javadoc είναι ένα αυτόνομο πρόγραμμα που συνοδεύεται από εκδόσεις του κιτ ανάπτυξης Java της Oracle (JDK). Στην πραγματικότητα, δεν μπορείτε να το κατεβάσετε ξεχωριστά. Όταν κάνετε λήψη και εγκαταστήστε μία από τις εκδόσεις JDK της Oracle, θα εγκαταστήσει επίσης το Javadoc.

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

Με λίγα λόγια, το Javadoc σας δίνει τη δυνατότητα να γράψετε τον κώδικα και την τεκμηρίωσή του ταυτόχρονα. Απλοποιεί τη ροή εργασίας σας και σας επιτρέπει να χρησιμοποιείτε πιο αποτελεσματικά τον χρόνο σας.

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

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

• Ξεκινήστε με τους τρεις χαρακτήρες /**.
• Συμπεριλάβετε έναν αστερίσκο στην αρχή κάθε νέας γραμμής.
• Κλείσιμο με τους δύο χαρακτήρες */.

Στα σχόλια, μπορείτε να συμπεριλάβετε HTML στην τελική έξοδο και να συμπεριλάβετε ετικέτες που θα δημιουργήσουν συνδέσμους προς σχετικά μέρη της βάσης κωδίκων σας. Μπορείτε ακόμη να χρησιμοποιήσετε πράγματα όπως ετικέτες εικόνας HTML για να συμπεριλάβετε εικόνες στην τελική τεκμηρίωση. Μόλις εξοικειωθείτε με τη μορφή και τις διαθέσιμες ετικέτες, η σύνταξη τέτοιων σχολίων είναι παιχνιδάκι.

Ακολουθεί ένα παράδειγμα για την απεικόνιση απλών σχολίων Javadoc που περιγράφουν μια λειτουργία που λαμβάνει μια εικόνα από μια διεύθυνση URL και την εκτυπώνει στην οθόνη. Το σχόλιο προηγείται αμέσως της συνάρτησης και περιγράφει τι κάνει. Αυτό το μπλοκ σχολίων χρησιμοποιεί επίσης τρεις ετικέτες για συγκεκριμένες ενότητες: @παραμ, @ΕΠΙΣΤΡΟΦΗ, και @βλέπω.

/**
* Επιστρέφει ένα αντικείμενο εικόνας που μπορεί στη συνέχεια να ζωγραφιστεί στην οθόνη.
* Το όρισμα url πρέπει να προσδιορίζει μια απόλυτη {@Σύνδεσμος URL}. Το όνομα
* το όρισμα είναι ένας προσδιοριστής που σχετίζεται με το όρισμα url.
* 

* Αυτή η μέθοδος επιστρέφει πάντα αμέσως, είτε όχι
* η εικόνα υπάρχει. Πότε Αυτό Η μικροεφαρμογή επιχειρεί να σχεδιάσει την εικόνα
* στην οθόνη, τα δεδομένα θα φορτωθούν. Τα πρωτόγονα γραφικά
* που σχεδιάζουν την εικόνα θα ζωγραφίζουν σταδιακά στην οθόνη.
*
* @παραμ url μια απόλυτη διεύθυνση URL που δίνει τη βασική τοποθεσία της εικόνας
* @παραμ ονομάστε τη θέση της εικόνας, σε σχέση με το όρισμα url
* @ΕΠΙΣΤΡΟΦΗ την εικόνα στο καθορισμένο URL
* @βλέπω Εικόνα
*/
δημόσιο Εικόνα getImage(URL url, όνομα συμβολοσειράς){
προσπαθήστε {
ΕΠΙΣΤΡΟΦΗ getImage(νέος URL(url, όνομα));
 } σύλληψη (MalformedURLException e) {
ΕΠΙΣΤΡΟΦΗμηδενικό;
 }
}

Όταν το Javadoc επεξεργάζεται τον παραπάνω κώδικα, δημιουργεί μια ιστοσελίδα παρόμοια με την ακόλουθη:

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

Οι @tags που χρησιμοποιούνται στο τέλος του σχολίου δημιουργούν το Παράμετροι, Επιστροφές, και Δείτε επίσης ενότητες που βλέπετε.

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

ο @ΕΠΙΣΤΡΟΦΗ Η ετικέτα τεκμηριώνει την τιμή που επιστρέφει η συνάρτηση, εάν υπάρχει. Μπορεί να είναι μια απλή μονολεκτική περιγραφή ή πολλές προτάσεις, ανάλογα με τις περιστάσεις.

ο @βλέπω Η ετικέτα σάς επιτρέπει να προσθέτετε ετικέτες σε άλλες συναρτήσεις που είναι σχετικές ή σχετικές. Σε αυτήν την περίπτωση, η ετικέτα @see αναφέρεται σε μια άλλη συνάρτηση που ονομάζεται απλώς Εικόνα. Σημειώστε ότι οι αναφορές που γίνονται με αυτήν την ετικέτα είναι σύνδεσμοι με δυνατότητα κλικ, επιτρέποντας στον αναγνώστη να μεταβεί στο αναφερόμενο στοιχείο στον τελικό HTML.

Υπάρχουν περισσότερες διαθέσιμες ετικέτες, όπως @version, @author, @exception και άλλες. Όταν χρησιμοποιούνται σωστά, οι ετικέτες βοηθούν στη συσχέτιση στοιχείων μεταξύ τους και καθιστούν δυνατή την εύκολη πλοήγηση στην τεκμηρίωση.

Εκτέλεση Javadoc στον πηγαίο κώδικα σας

Καλείτε το Javadoc στη γραμμή εντολών. Μπορείτε να το εκτελέσετε σε μεμονωμένα αρχεία, ολόκληρους καταλόγους, πακέτα java ή σε μια λίστα μεμονωμένων αρχείων. Από προεπιλογή, το Javadoc θα δημιουργήσει τα αρχεία τεκμηρίωσης HTML στον κατάλογο όπου εισάγετε την εντολή. Για να λάβετε βοήθεια σχετικά με τις συγκεκριμένες διαθέσιμες εντολές, απλώς πληκτρολογήστε:

javadoc --βοήθεια

Για να δείτε τι ακριβώς μπορεί να κάνει η Javadoc με περισσότερες λεπτομέρειες, ανατρέξτε στην επίσημη τεκμηρίωση από Μαντείο. Για να δημιουργήσετε ένα γρήγορο σύνολο τεκμηρίωσης σε ένα μεμονωμένο αρχείο ή κατάλογο μπορείτε να εισέλθετε javadoc στη γραμμή εντολών ακολουθούμενη από όνομα αρχείου ή μπαλαντέρ.

javadoc ~/code/όνομα αρχείου.java
javadoc ~/code/*.Ιάβα

Παραπάνω είναι μια λίστα με τα αρχεία και τους καταλόγους που έχει δημιουργήσει η Javadoc. Όπως μπορείτε να δείτε, υπάρχουν αρκετά από αυτά. Για το λόγο αυτό, θα πρέπει να είστε βέβαιοι ότι δεν βρίσκεστε στον ίδιο κατάλογο με τον πηγαίο κώδικα κατά την εκτέλεση του προγράμματος. Κάτι τέτοιο θα μπορούσε να δημιουργήσει ένα μεγάλο χάος.

Για να προβάλετε τα πρόσφατα δημιουργημένα έγγραφά σας, απλώς ανοίξτε το index.html αρχείο στο πρόγραμμα περιήγησης που προτιμάτε. Θα λάβετε μια σελίδα όπως η παρακάτω:

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

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

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

Τα 8 καλύτερα Java Blogs για προγραμματιστές

Διαβάστε Επόμενο