Βελτιώστε την τεκμηρίωση και τη δοκιμή κώδικα με ένα εύκολο βήμα με παραδείγματα λειτουργιών.
Βασικά Takeaways
- Παραδείγματα συναρτήσεων στο Go είναι αποσπάσματα κώδικα με δυνατότητα δοκιμής που χρησιμεύουν ως τεκμηρίωση και μπορούν να χρησιμοποιηθούν για την επαλήθευση της ορθότητας.
- Τα παραδείγματα συναρτήσεων ακολουθούν μια σύμβαση ονομασίας και μπορούν να οριστούν για πακέτα, συναρτήσεις, τύπους και μεθόδους.
- Τα παραδείγματα λειτουργιών είναι εκτελέσιμα τεστ και μπορούν να χρησιμοποιηθούν για να διασφαλιστεί αξιόπιστος κώδικας και να διατηρηθεί η τεκμηρίωση ενημερωμένη.
Ένα από τα δυνατά σημεία της Go είναι η πληθώρα ενσωματωμένων δυνατοτήτων δοκιμών και τεκμηρίωσης. Μεταξύ αυτών είναι ένα εξαιρετικά χρήσιμο εργαλείο που ονομάζεται "παράδειγμα συναρτήσεων" που μπορεί να σας βοηθήσει να ελέγξετε τον κώδικά σας και να τον εξηγήσετε σε άλλους.
Ως προγραμματιστής Go, θα πρέπει να κατανοήσετε ακριβώς ποιες είναι οι λειτουργίες παραδείγματος και πώς μπορείτε να τις χρησιμοποιήσετε για να δημιουργήσετε λογισμικό με δυνατότητα συντήρησης.
Τι είναι οι παραδειγματικές συναρτήσεις;
Οι παραδειγματικές συναρτήσεις (ή παραδείγματα) στο Golang είναι αποσπάσματα κώδικα που μπορείτε να δοκιμάσετε και μπορείτε να προσθέσετε σε ένα πακέτο ως τεκμηρίωση και να επαληθεύσετε την ορθότητά τους. Οι παραδειγματικές συναρτήσεις δεν λαμβάνουν παραμέτρους και δεν επιστρέφουν επίσης αποτέλεσμα.
Φανταστείτε ότι έχετε το εξής Πολλαπλασιάζω λειτουργία στο έργο σας:
funcMultiply(a, b int)int {
return a * b
}
Ένα παράδειγμα συνάρτησης για Πολλαπλασιάζω θα μοιάζει με αυτό:
funcExampleMultiply() {
fmt.Println(Multiply(4, 5))
// Output: 2
}
Οι παραδειγματικές συναρτήσεις χρησιμοποιούν μια παρόμοια σύμβαση ονομασίας για τη δοκιμή συναρτήσεων. Ορίστε ένα παράδειγμα συνάρτησης προσθέτοντας το όνομα της συνάρτησης ως επίθημα στο "Παράδειγμα", όπως συμβαίνει με Παράδειγμα Πολλαπλασιασμός εδώ.
Ρίχνοντας μια πιο προσεκτική ματιά στα παραδείγματα συναρτήσεων
Ο κώδικας στην προηγούμενη ενότητα δείχνει τη βασική δομή μιας συνάρτησης παραδείγματος. Αυτό που αποτελεί ένα παράδειγμα είναι το όνομα, το σώμα της συνάρτησης και ένα προαιρετικό σχόλιο εξόδου στο τέλος της συνάρτησης.
Όταν προσθέτετε το σχόλιο εξόδου, το Go μεταγλωττίζει και εκτελεί το παράδειγμα για να επαληθεύσει την ορθότητά του, αλλά χωρίς το σχόλιο, το Go μεταγλωττίζει μόνο τη συνάρτηση παραδείγματος, δεν την εκτελεί.
Μπορείτε να ορίσετε ένα παράδειγμα για ένα πακέτο, μια συνάρτηση, έναν τύπο και μια μέθοδο σε έναν τύπο.
Ο καθορισμός παραδειγμάτων για διαφορετικές οντότητες απαιτεί διαφορετικές προσεγγίσεις.
- Για να ορίσετε ένα παράδειγμα για ένα πακέτο, απλώς καλέστε τη συνάρτησή σας Παράδειγμα(), χωρίς κανένα επίθημα. Για παράδειγμα, εδώ είναι ένα παράδειγμα σε επίπεδο πακέτου:
funcExample() {
fmt.Println("Hello, world!")
// Output:
// Hello, world!
} - Για να ορίσετε ένα παράδειγμα για μια συνάρτηση, απλώς προσθέστε το όνομα της συνάρτησης ως επίθημα όπως μάθατε νωρίτερα.
funcExampleMultiply() {
fmt.Println(Multiply(4,5))
// Output: 2
} - Για να ορίσετε ένα παράδειγμα για έναν τύπο, προσθέστε το όνομα ως επίθημα Παράδειγμα. Εδώ είναι ένα παράδειγμα:
type MyStruct struct {
// ...
}funcExampleMyStruct() {
// ...
} - Και τέλος, για μια μέθοδο σε έναν συγκεκριμένο τύπο, προσθέτετε το όνομα τύπου, μια υπογράμμιση και μετά το όνομα της μεθόδου. Εδώ είναι μια επίδειξη:
func(m *MyStruct)MyMethod() {
// ...
}funcExampleMyStruct_MyMethod() {
// ...
}
Μπορείτε να ορίσετε πολλά παραδείγματα για μια οντότητα προσθέτοντας μια επιπλέον υπογράμμιση και ένα επίθημα που αρχίζει με πεζό γράμμα. Για παράδειγμα, Παράδειγμα Πολλαπλός_δευτερόλεπτο, ExampleMyStruct_MyMethod_second.
Μπορείτε επίσης να έχετε ένα μεγαλύτερο παράδειγμα για να εξηγήσετε τη σύνθετη λογική χρησιμοποιώντας a ολόκληρο παράδειγμα αρχείου.
Ένα ολόκληρο παράδειγμα αρχείου είναι ένα αρχείο που καταλήγει σε _test.go και περιέχει ακριβώς ένα παράδειγμα συνάρτησης, καμία συνάρτηση δοκιμής ή συγκριτικής αξιολόγησης και τουλάχιστον μία άλλη δήλωση σε επίπεδο πακέτου. Όταν εμφανίζονται τέτοια παραδείγματα, το godoc θα εμφανίσει ολόκληρο το αρχείο. - Το ιστολόγιο go dev
Η μηχανή Go αναγνωρίζει και χειρίζεται τις παραδειγματικές σας συναρτήσεις σύμφωνα με τον τρόπο που τις ορίζετε.
Μπορείτε να χρησιμοποιήσετε το Μη διατεταγμένη έξοδος εναλλακτική λύση για σχόλια εξόδου. Αυτό είναι ιδιαίτερα χρήσιμο σε σενάρια όπου η συνάρτησή σας επιστρέφει μια λίστα που δεν αναμένεται με συγκεκριμένη σειρά.
Τεκμηρίωση του Κώδικά σας με Παραδείγματα Συναρτήσεων
Οι λειτουργίες παραδείγματος είναι χρήσιμες τόσο για σκοπούς τεκμηρίωσης όσο και για σκοπούς δοκιμής. Μια συνάρτηση παραδείγματος συνήθως κάνει καλύτερη δουλειά στην εξήγηση της συμπεριφοράς από τα σχόλια.
Οπως ακριβώς Javadoc της Java, Πηγαίνετε ενσωματωμένο εργαλείο τεκμηρίωσης, godoc, βοηθά τον κώδικα του εγγράφου εύκολα. Αλλά θα θέλετε να τεκμηριώσετε μερικές βιβλιοθήκες και λειτουργίες μαζί για να δώσετε μια πληρέστερη κατανόηση του τρόπου λειτουργίας τους. Τα παραδείγματα εξαλείφουν αυτήν την οπισθοδρόμηση καθώς μπορούν να επιδείξουν τις αλληλεπιδράσεις μεταξύ διαφόρων μονάδων ενός πακέτου.
ο godoc Το εργαλείο συσχετίζει αυτόματα παραδείγματα με τις λειτουργίες, τους τύπους και τα πακέτα στα οποία ανήκουν, ανάλογα με τις προδιαγραφές σας. Προχωρά επίσης ένα βήμα παραπέρα επιτρέποντας τον πειραματισμό μέσα στη διεπαφή ιστού τεκμηρίωσης.
Μπορείτε να δοκιμάσετε ένα πακέτο ή μια μέθοδο απευθείας από την τεκμηρίωση προτού το χρησιμοποιήσετε στον κώδικά σας.
Αυτή η εικόνα δείχνει ένα παράδειγμα για το json. Εγκυρος λειτουργία κάτω από κωδικοποίηση/json:
Χρήση παραδειγμάτων συναρτήσεων για δοκιμή μονάδας
Οι συναρτήσεις παραδείγματος Go είναι επίσης εκτελέσιμα τεστ. Όταν τρέχετε το πήγαινε δοκιμή εντολή, ο κινητήρας εκτελεί κάθε παράδειγμα λειτουργίας με ένα τελικό σχόλιο εξόδου και διασφαλίζει ότι η έξοδος του ταιριάζει με αυτό που υπάρχει στο σχόλιο.
Αυτή η δυνατότητα είναι χρήσιμη με πολλούς τρόπους. Μπορεί να χρησιμεύσει ως ένα επιπλέον στρώμα του δοκιμή για την εξασφάλιση αξιόπιστου κώδικα, σας βοηθά επίσης να παρακολουθείτε την τεκμηρίωσή σας καθώς αλλάζει ο κωδικός σας.
Για παράδειγμα, εάν κάνετε μια αλλαγή που επηρεάζει τον τρόπο εκτέλεσης μιας συγκεκριμένης συνάρτησης και το αποτέλεσμα που επιστρέφει. Εάν δεν ενημερώσετε το σχόλιο εξόδου στο παράδειγμα για να ανταποκρίνεται στις νέες αλλαγές, οι δοκιμές για αυτό το παράδειγμα θα αποτύχουν.
Αυτό βοηθάει πολύ στην αποφυγή παλιών εγγράφων, καθώς η τεκμηρίωσή σας θα είναι πάντα ενημερωμένη με τον κώδικα.
Παράδειγμα Λειτουργιών Παραγωγή αξιόπιστου κώδικα και τεκμηρίωσης
Η τεκμηρίωση είναι ένα ουσιαστικό μέρος της ανάπτυξης λογισμικού, αλλά λίγες γλώσσες σάς προσφέρουν μια τόσο ισχυρή πλατφόρμα για να τεκμηριώσετε και να δοκιμάσετε τον κώδικά σας.
Το Go συνοδεύεται από όλα όσα χρειάζεστε για να δημιουργήσετε ποιοτική τεκμηρίωση για το λογισμικό σας και οι λειτουργίες παραδείγματος αποτελούν ζωτικό μέρος αυτού. Χρησιμοποιήστε παραδείγματα για να βοηθήσετε τους χρήστες και τους συνεργάτες να υιοθετήσουν και να κατανοήσουν τον κώδικά σας πιο γρήγορα.
