Πώς να τεκμηριώσετε τον κώδικα Python χρησιμοποιώντας Docstrings

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

Τι είναι τα Docstrings;

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

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

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

Πώς να γράψετε εγγραφές

Συνήθως συμπεριλαμβάνετε συμβολοσειρές εγγράφων στην αρχή του μπλοκ κώδικα που θέλετε να τεκμηριώσετε. Πρέπει να τα περικλείσετε σε τριπλά εισαγωγικά (). Μπορείτε να γράψετε συμβολοσειρές εγγράφων μίας γραμμής ή συμβολοσειρές εγγράφων πολλών γραμμών.

Οι συμβολοσειρές εγγράφων μιας γραμμής είναι κατάλληλες για απλό κώδικα που δεν απαιτεί πολλή τεκμηρίωση.

Παρακάτω είναι ένα παράδειγμα μιας συνάρτησης που ονομάζεται πολλαπλασιασμός. Το docstring εξηγεί ότι η συνάρτηση πολλαπλασιασμού παίρνει δύο αριθμούς, τους πολλαπλασιάζει και επιστρέφει το αποτέλεσμα.

defπολλαπλασιάζω(α, β):
Πολλαπλασιάζει δύο αριθμούς και επιστρέφει το αποτέλεσμα
ΕΠΙΣΤΡΟΦΗ α * β

Χρησιμοποιήστε συμβολοσειρές εγγράφων πολλών γραμμών για πιο περίπλοκο κώδικα που χρειάζεται λεπτομερή τεκμηρίωση.

Εξετάστε την ακόλουθη κατηγορία αυτοκινήτου:

τάξηΑυτοκίνητο:

 ΕΝΑ τάξηαντιπροσωπεύονταςένααυτοκίνητοαντικείμενο.
 Γνωρίσματα:
 χιλιόμετρα (float): Η τρέχουσα χιλιομετρική απόσταση του αυτοκινήτου.
 Μέθοδοι:
 οδήγηση (μίλια): Οδηγεί το αυτοκίνητο Για τον καθορισμένο αριθμό μιλίων.

def__μέσα σε αυτό__(εαυτός, χιλιόμετρα):
 αυτο.mileage = χιλιόμετρα
defοδηγώ(εαυτός, μίλια):

 Οδηγεί το αυτοκίνητο Για τον καθορισμένο αριθμό μιλίων.
 Args:
 μίλια (float): Ο αριθμός των μιλίων προς οδήγηση.
 Επιστροφές:
Κανένας

 αυτο.χιλιόμετρα += μίλια

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

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

• Δυνατότητα συντήρησης κώδικα: Παρέχοντας μια σαφή περιγραφή του τρόπου λειτουργίας του κώδικα, οι συμβολοσειρές εγγράφων βοηθούν τους προγραμματιστές να τροποποιήσουν και να ενημερώσουν τον κώδικα χωρίς να εισάγουν σφάλματα.
• Ευκολότερη συνεργασία: Όταν πολλοί προγραμματιστές συνεργάζονται στην ίδια βάση κώδικα—για παράδειγμα, με το Εργαλείο ζωντανής κοινής χρήσης του Visual Studio—οι συμβολοσειρές εγγράφων επιτρέπουν στους προγραμματιστές να τεκμηριώνουν τον κώδικα με συνέπεια, ώστε όλοι στην ομάδα να μπορούν να τον κατανοήσουν.
• Βελτιωμένη αναγνωσιμότητα κώδικα: Οι συμβολοσειρές εγγράφων παρέχουν μια περίληψη υψηλού επιπέδου του τι επιτρέπει ο κώδικας όποιος διαβάζει τον κώδικα για να καταλάβει γρήγορα τον σκοπό του χωρίς να διαβάσει ολόκληρο τον κώδικα ΟΙΚΟΔΟΜΙΚΟ ΤΕΤΡΑΓΩΝΟ.

Μορφές Docstring

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

Μια βασική μορφή εγγράφων έχει τις ακόλουθες ενότητες:

• Γραμμή σύνοψης: Μια σύνοψη μιας γραμμής του τι κάνει ο κώδικας.
• Ορίσματα: Πληροφορίες σχετικά με τα ορίσματα που αναμένει η συνάρτηση, συμπεριλαμβανομένων των τύπων δεδομένων τους.
• Επιστρεφόμενη τιμή: Πληροφορίες σχετικά με την επιστρεφόμενη τιμή της συνάρτησης συμπεριλαμβανομένου του τύπου δεδομένων της.
• Αυξήσεις (προαιρετικό): Πληροφορίες σχετικά με τυχόν εξαιρέσεις που μπορεί να δημιουργήσει η συνάρτηση.

Αυτή είναι απλώς μια βασική μορφή, καθώς υπάρχουν άλλες μορφές που μπορείτε να επιλέξετε για να βασίσετε τις συμβολοσειρές εγγράφων σας. Τα πιο δημοφιλή είναι το Epytext, το reStructuredText (γνωστό και ως reST), το NumPy και οι συμβολοσειρές εγγράφων Google. Κάθε μία από αυτές τις μορφές έχει τη δική της σύνταξη όπως φαίνεται στα ακόλουθα παραδείγματα:

Επικείμενο

Μια συμβολοσειρά εγγράφων που ακολουθεί τη μορφή Epytext:

defπολλαπλασιάζω(α, β):

 Πολλαπλασιάστε δύο αριθμούς μαζί.
 @param a: Ο πρώτος αριθμός που πολλαπλασιάζεται.
 @type a: int
 @param b: Ο δεύτερος αριθμός που πρέπει να πολλαπλασιαστεί.
 @τύπος β: ενθ
 @return: Το γινόμενο των δύο αριθμών.
 @rtype: ενθ

ΕΠΙΣΤΡΟΦΗ α * β

reStructuredText (reST)

Μια συμβολοσειρά εγγράφων που ακολουθεί τη μορφή reST:

defπολλαπλασιάζω(α, β):

 Πολλαπλασιάστε δύο αριθμούς μαζί.
 :param a: Ο πρώτος αριθμός που πολλαπλασιάζεται.
 :type a: int
 :param b: Ο δεύτερος αριθμός που πρέπει να πολλαπλασιαστεί.
 :type b: int
 :ΕΠΙΣΤΡΟΦΗ: Το γινόμενο των δύο αριθμών.
 :rtype: ενθ

ΕΠΙΣΤΡΟΦΗ α * β

NumPy

Μια συμβολοσειρά εγγράφων που ακολουθεί τη μορφή NumPy:

defπολλαπλασιάζω(α, β):

 Πολλαπλασιάστε δύο αριθμούς μαζί.
 Παράμετροι

 α: ενθ
 Ο πρώτος αριθμός που πολλαπλασιάζεται.
 β: ενθ
 Ο δεύτερος αριθμός που πολλαπλασιάζεται.
 Επιστροφές

 ενθ
 Το γινόμενο των δύο αριθμών.

ΕΠΙΣΤΡΟΦΗ α * β

Google

Μια συμβολοσειρά εγγράφων που ακολουθεί τη μορφή Google:

defπολλαπλασιάζω(α, β):

 Πολλαπλασιάστε δύο αριθμούς μαζί.
 Args:
 a (int): Ο πρώτος αριθμός που πολλαπλασιάζεται.
 b (int): Ο δεύτερος αριθμός που πρέπει να πολλαπλασιαστεί.
 Επιστροφές:
 int: Το γινόμενο των δύο αριθμών.

ΕΠΙΣΤΡΟΦΗ α * β

Παρόλο που και οι τέσσερις μορφές εγγράφων παρέχουν χρήσιμη τεκμηρίωση για τη λειτουργία πολλαπλασιασμού, οι μορφές NumPy και Google είναι πιο ευανάγνωστες από τις μορφές Epytext και reST.

Πώς να συμπεριλάβετε δοκιμές στα Docstrings

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

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

defπολλαπλασιάζω(α, β):

 Πολλαπλασιάστε δύο αριθμούς μαζί.
 Παράμετροι

 α: ενθ
 Ο πρώτος αριθμός που πολλαπλασιάζεται.
 β: ενθ
 Ο δεύτερος αριθμός που πολλαπλασιάζεται.
 Επιστροφές

 ενθ
 Το γινόμενο των δύο αριθμών.
 Παραδείγματα

 >>> πολλαπλασιάζω(2, 3)
6
 >>> πολλαπλασιάζω(0, 10)
0
 >>> πολλαπλασιάζω(-1, 5)
-5

ΕΠΙΣΤΡΟΦΗ α * β

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

python -m doctest multiply.py

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

Πώς να δημιουργήσετε τεκμηρίωση από το Docstrings

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

Μία από τις πιο δημοφιλείς γεννήτριες τεκμηρίωσης που μπορείτε να χρησιμοποιήσετε είναι η Sphinx. Υποστηρίζει από προεπιλογή τη μορφή docstring reST, αλλά μπορείτε να τη διαμορφώσετε ώστε να λειτουργεί με τη μορφή Google ή NumPy.