Όταν σκέφτεστε τον προγραμματισμό, είναι φυσικό να εστιάσετε σε θέματα όπως γλώσσες, αλγόριθμοι και εντοπισμός σφαλμάτων. Αλλά η τεχνική τεκμηρίωση μπορεί να είναι εξίσου σημαντική για να γίνει σωστά.
Χωρίς καλή τεκμηρίωση, η επαναχρησιμοποίηση του κώδικα μπορεί να υποφέρει. Οι χρήστες που είναι νέοι σε μια βάση κωδικών μπορούν εύκολα να χαθούν ή να απογοητευτούν εάν η τεκμηρίωση δεν είναι μέχρι το μηδέν. Δεν είναι μόνο σημαντικό να κατανοήσουμε τι κάνει ένα πρόγραμμα, αλλά πώς —ή και γιατί— το κάνει.
Πακέτα όπως το Pydoc για Python και το Javadoc για Java βοηθούν αυτοματοποιώντας μέρος της διαδικασίας. Το εργαλείο Godoc κάνει ακριβώς το ίδιο για το Go.
Τι είναι ο Godoc;
Το Godoc είναι ένα πακέτο Go που σας επιτρέπει να δημιουργείτε, να διαχειρίζεστε και να χρησιμοποιείτε την τεκμηρίωση Go στο "the Go way". Το Go way είναι ένα σύνολο αρχών που, ως προγραμματιστής Go, θα πρέπει να ακολουθήσετε για να βελτιώσετε την ποιότητα του κώδικα.
Χρησιμοποιώντας το Godoc, μπορείτε εύκολα να διαβάσετε την τεκμηρίωση και τον κώδικα άλλων προγραμματιστών. Μπορείτε επίσης να αυτοματοποιήσετε τη δημιουργία της δικής σας τεκμηρίωσης και να τη δημοσιεύσετε χρησιμοποιώντας το Godoc.
Ο Godoc είναι παρόμοιος με Javadoc, το αρχείο τεκμηρίωσης κώδικα για Java. Και οι δύο χρησιμοποιούν σχόλια και κώδικα σε ενότητες για τη δημιουργία τεκμηρίωσης. Και τα δύο εργαλεία δομούν αυτήν την τεκμηρίωση σε HTML, ώστε να μπορείτε να την προβάλετε σε ένα πρόγραμμα περιήγησης.
Ξεκινώντας με τον Godoc
Η χρήση του Godoc είναι εύκολη. Για να ξεκινήσετε, εγκαταστήστε το πακέτο Godoc από τον ιστότοπο golang χρησιμοποιώντας αυτήν την εντολή:
πηγαίνω λάβετε το golang.org/x/tools/cmd/godoc
Η εκτέλεση αυτής της εντολής θα εγκαταστήσει το Godoc στον καθορισμένο χώρο εργασίας σας. Μόλις ολοκληρωθεί, θα πρέπει να μπορείτε να εκτελέσετε το godoc εντολή σε ένα τερματικό. Εάν υπάρχουν σφάλματα με την εγκατάστασή σας, δοκιμάστε να ενημερώσετε το Μετάβαση σε μια πρόσφατη έκδοση.
Ο Godoc αναζητά σχόλια μίας και πολλαπλής γραμμής για να συμπεριλάβει στην τεκμηρίωση που δημιουργεί.
Φροντίστε να μορφοποιήσετε τον κώδικα με τον τρόπο Go, όπως εξηγείται η δημοσίευση Effective Go από την ομάδα Go για τα καλύτερα αποτελέσματα.
Ακολουθεί ένα παράδειγμα χρήσης σχολίων μονής γραμμής σε στυλ C++:
// Ο χρήστης είναι ένα μοντέλο δομής που περιέχει
τύπος Χρήστης struct {
}
Μπορείτε επίσης να χρησιμοποιήσετε σχόλια μπλοκ τύπου C:
/*
Ο χρήστης είναι μια προσαρμοσμένη δομή δεδομένωνΜπορείτε να συμπεριλάβετε οποιοδήποτε κείμενο εδώ και ο διακομιστής Godoc θα το μορφοποιήσει όταν το εκτελείτε.
*/
τύπος Χρήστης struct {
}
Στα παραπάνω σχόλια, ο "Χρήστης" ξεκινά τις προτάσεις επειδή το σχόλιο περιγράφει τι κάνει η δομή χρήστη. Αυτό είναι ένα από τα πολλά θέματα που συζητά το Go way. Η έναρξη των προτάσεων τεκμηρίωσης με ένα χρήσιμο όνομα είναι ζωτικής σημασίας, καθώς η πρώτη πρόταση εμφανίζεται στη λίστα πακέτων.
Εκτέλεση διακομιστή Godoc
Αφού σχολιάσετε τον κωδικό σας, μπορείτε να εκτελέσετε το godoc εντολή στο τερματικό σας, από τον κατάλογο κωδικών του έργου σας.
Συμβατικά, οι προγραμματιστές Go χρησιμοποιούν θύρα 6060 για φιλοξενία τεκμηρίωσης. Αυτή είναι η εντολή για την εκτέλεση ενός διακομιστή Godoc σε αυτήν τη θύρα:
godoc -http=:6060
Η παραπάνω εντολή φιλοξενεί την τεκμηρίωση του κώδικα σας localhost ή 127.0.0.1. Η θύρα δεν χρειάζεται να είναι 6060. Το godoc θα τρέχει σε οποιοδήποτε μη κατειλημμένο λιμάνι. Ωστόσο, είναι πάντα καλύτερο να ακολουθείτε τις συμβάσεις τεκμηρίωσης Go.
Αφού εκτελέσετε την εντολή, μπορείτε να προβάλετε την τεκμηρίωσή σας σε ένα πρόγραμμα περιήγησης κάνοντας μια επίσκεψη localhost: 6060. Ο χρόνος που χρειάζεται ο Godoc για να δημιουργήσει την τεκμηρίωσή σας θα εξαρτηθεί από το μέγεθος και την πολυπλοκότητά του.
Ο παρακάτω κώδικας ακολουθεί τον τρόπο Go, σε αυτήν την περίπτωση χρησιμοποιώντας σχόλια μιας γραμμής.
// όνομα του πακέτου
πακέτο χρήστηςΤο // fmt είναι υπεύθυνο για τη μορφοποίηση
εισαγωγή (
"fmt"
)// Ο χρήστης είναι μια δομή ανθρώπινων δεδομένων
τύπος Χρήστης struct {
Ηλικία ενθ
Ονομα σειρά
}funcκύριος() {
// ανθρώπινος είναι μια προετοιμασία της δομής χρήστη
άνθρωπος := Χρήστης {
Ηλικία: 0,
Όνομα: "πρόσωπο",
}fmt. Println (ανθρώπινο. ΜΙΛΑ ρε())
}
// Το Talk είναι μια μέθοδος της δομής χρήστη
func(Χρήστης δέκτη)ΜΙΛΑ ρε()σειρά {
ΕΠΙΣΤΡΟΦΗ "Κάθε χρήστης μπορεί να πει κάτι!"
}
Εάν εκτελείτε το Godoc στην παραπάνω ενότητα κώδικα, θα πρέπει να δείτε την έξοδο να μοιάζει με αυτό:
Παρατηρήστε ότι είναι σε μια οικεία μορφή, παρόμοια με αυτή που θα βρείτε στον επίσημο ιστότοπο τεκμηρίωσης Go.
Ο Godoc χρησιμοποιεί το σχόλιο που προηγείται της δήλωσης πακέτου ως το ΣΦΑΙΡΙΚΗ ΕΙΚΟΝΑ. Βεβαιωθείτε ότι αυτό το σχόλιο περιγράφει τι κάνει το πρόγραμμά σας.
ο Δείκτης περιέχει συνδέσμους προς τις δηλώσεις τύπου και τις μεθόδους, ώστε να μπορείτε να πλοηγηθείτε γρήγορα σε αυτές.
Το Godoc παρέχει επίσης λειτουργικότητα για την προβολή του πηγαίου κώδικα που αποτελεί το πακέτο στο Αρχεία πακέτου Ενότητα.
Βελτίωση της τεκμηρίωσής σας χρησιμοποιώντας το Godoc
Μπορείτε να συμπεριλάβετε περισσότερα από απλό κείμενο στην τεκμηρίωση του Godoc. Μπορείτε να προσθέσετε διευθύνσεις URL για τις οποίες ο Godoc θα δημιουργήσει συνδέσμους και θα δομήσει τα σχόλιά σας σε παραγράφους.
Εάν θέλετε να συνδέσετε έναν πόρο, γράψτε τη διεύθυνση URL στο σχόλιό σας και ο Godoc θα την αναγνωρίσει και θα προσθέσει έναν σύνδεσμο. Για τις παραγράφους, αφήστε μια κενή γραμμή σχολίων.
// Κύριο πακέτο
πακέτο κύριος// Το έγγραφο αντιπροσωπεύει ένα κανονικό έγγραφο.
//
// Συνδέω με https://google.com
τύπος Εγγραφο struct {
σελίδες ενθ
βιβλιογραφικές αναφορές σειρά
υπογεγραμμένος bool
}// Το Write γράφει ένα νέο έγγραφο στο χώρο αποθήκευσης
//
// Μπορείτε να μάθετε για τη γραφή από τη Wikipedia.com
funcΓράφω() {
}
Σημειώστε ότι ο Godoc απαιτεί από εσάς να γράψετε πλήρως τις διευθύνσεις URL για να τις συνδέσει. Σε αυτό το παράδειγμα, η διεύθυνση URL της Google περιλαμβάνει το https:// πρόθεμα, οπότε ο Godoc προσθέτει έναν σύνδεσμο σε αυτό. Δεδομένου ότι ο τομέας της Wikipedia δεν είναι μια πλήρης διεύθυνση URL από μόνος του, ο Godoc θα τον αφήσει ήσυχο.
Ακολουθούν ορισμένες καλύτερες αρχές που πρέπει να εφαρμόζετε κατά την τεκμηρίωση του κώδικα Go:
- Διατηρήστε την τεκμηρίωσή σας απλή και συνοπτική.
- Ξεκινήστε την πρόταση των συναρτήσεων, των τύπων και των δηλώσεων μεταβλητών με το όνομά τους.
- Ξεκινήστε μια γραμμή με μια εσοχή για να την προδιαμορφώσετε ως κώδικα.
- Σχόλια που ξεκινούν "BUG(όνομα)" όπως "BUG(joe): Αυτό δεν λειτουργεί" είναι ιδιαίτερα. Ο Godoc θα τα αναγνωρίσει ως σφάλματα και θα τα αναφέρει στη δική του ενότητα της τεκμηρίωσης.
Ο Godoc μπορεί να διευκολύνει τα προβλήματα τεκμηρίωσής σας
Χρησιμοποιώντας το Godoc, μπορείτε να είστε πιο παραγωγικοί και να ανησυχείτε λιγότερο για την προσπάθεια τεκμηρίωσης των προγραμμάτων σας με το χέρι.
Θα πρέπει να διατηρείτε την τεκμηρίωσή σας ακριβή, λεπτομερή και σε τέτοιο σημείο ώστε να διευκολύνετε το κοινό-στόχο σας να διαβάσει και να κατανοήσει. Είναι επίσης ζωτικής σημασίας να διατηρείτε ενημερωμένα τα σχόλια κώδικα καθώς τροποποιείτε το πρόγραμμά σας.
Ανατρέξτε στην τεκμηρίωση του πακέτου Godoc για να μάθετε περισσότερα σχετικά με τη χρήση του Godoc.
