Δημοσιεύτηκε: 17 Νοέμ 2010, 17:50
επίσης τι σημαίνει αυτό;
- Κώδικας: Επιλογή όλων
Συμβολοσειρές τεκμηρίωσης (DocStrings)
Η Python έχει ένα θαυμάσιο χαρακτηριστικό που ονομάζεται συμβολοσειρές τεκμηρίωσης (documentation strings) και συνήθως αναφέρεται με τη συντομογραφία DocStrings. Οι συμβολοσειρές τεκμηρίωσης είναι ένα σπουδαίο εργαλείο που πρέπει να χρησιμοποιείτε διότι βοηθάει να τεκμηριώσετε το πρόγραμμα καλύτερα και έτσι γίνεται πιο εύκολα κατανοητό. Το εντυπωσιακό είναι ότι μπορούμε να πάρουμε επιστροφή τη συμβολοσειρά τεκμηρίωσης από μια συνάρτηση για παράδειγμα, ενώ το πρόγραμμα πραγματικά τρέχει!
Παράδειγμα:
#!/usr/bin/python
# Filename: func_doc.py
def printMax(x, y):
'''Prints the maximum of two numbers.
Oι δύο τιμές πρέπει να είναι ακέραιοι αριθμοί.'''
x = int(x) # μετέτρεψε σε ακέραιους αριθμούς αν είναι δυνατόν
y = int(y)
if x > y:
print(x, 'is maximum')
else:
print(y, 'is maximum')
printMax(3, 5)
print(printMax.__doc__)
Έξοδος:
$ python func_doc.py
5 is maximum
Prints the maximum of two numbers.
Οι δύο τιμές πρέπει να είναι ακέραιοι αριθμοί.
Πώς δουλεύει:
Mία συμβολοσειρά στην πρώτη λογική γραμμή της συνάρτησης είναι η συμβολοσειρά τεκμηρίωσης για αυτή τη συνάρτηση. Σημειώστε ότι οι συμβολοσειρές τεκμηρίωσης εφαρμόζονται και στα αρθρώματα (modules) και στις κλάσεις (classes), όπως θα μάθουμε στα αντίστοιχα κεφάλαια.
Η σύμβαση που ακολουθείται για μια συμβολοσειρά τεκμηρίωσης είναι μια συμβολοσειρά πολλών γραμμών, όπου η πρώτη γραμμή αρχίζει με ένα κεφαλαίο γράμμα και τελειώνει με μια τελεία. Κατόπιν η δεύτερη γραμμή είναι κενή και ακολουθεί η τρίτη γραμμή που έχει κάθε λεπτομερή εξήγηση. Προτείνεται να ακολουθείτε ακριβώς αυτή τη σύμβαση για όλες τις στοιχειοσειρές τεκμηρίωσης που αφορούν όλες τις μη τετριμμένες συναρτήσεις (non-trivial functions).
Μπορούμε να έχουμε πρόσβαση στη συμβολοσειρά τεκμηρίωσης της συνάρτησης printMax χρησιμοποιώντας το ιδιοχαρακτηριστικό (ονομασία που ανήκει σε) __doc__ (σημειώστε τις διπλές κάτω παύλες) της συνάρτησης. Θυμηθείτε όμως ότι η Python αντιμετωπίζει τα πάντα σαν αντικείμενα, και αυτό συμπεριλαμβάνει και τις συναρτήσεις. Θα μάθουμε περισσότερα για τα αντικείμενα στο κεφάλαιο για τις κλάσεις.
Εάν έχετε χρησιμοποιήσει την help() στην Python, τότε έχετε δει ήδη την χρήση των συμβολοσειρών τεκμηρίωσης. Αυτό που κάνει η help() είναι να φέρνει το ιδιοχαρακτηριστικό __doc__ της συνάρτησης και να το εμφανίζει με ένα καλοφτιαγμένο τρόπο. Mπορείτε να το δοκιμάσετε στην παραπάνω συνάρτηση αρκεί να συμπεριλάβουμε την help(printMax) στο πρόγραμμά μας. Θυμηθείτε να πατήσετε το q για κλείσετε τη help.
Μερικά αυτοματοποιημένα εργαλεία μπορούν να ανακτήσουν την τεκμηρίωση από το πρόγραμμά σας με αυτόν τον τρόπο. Συνεπώς συνιστάται να χρησιμοποιείτε συμβολοσειρές τεκμηρίωσης σε κάθε μη τετριμμενη συνάρτηση που γράφετε. Η εντολή pydoc που συνοδεύει την Python λειτουργεί παρόμοια με τη help() χρησιμοποιώντας τις docstrings.
[edit]