Προγραμματιστές Γιατί δεν πρέπει να παραλείψετε την τεκμηρίωση

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

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

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

Η καλή τεκμηρίωση βοηθά τους χρήστες

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

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

Ένα καλό σχέδιο σχεδίασης θα βοηθούσε πραγματικά τους χρήστες να σαρώσουν μέσα από κάθε τομή της τεκμηρίωσης χωρίς μάτι-στέλεχος. Μερικά καλά παραδείγματα (γνωστά και ως αγαπημένα μου) είναι τεκμηρίωση για το Bootstrap και το WordPress ' “Πρώτα βήματα με το WordPress”.

Βοηθά επίσης άλλους προγραμματιστές

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

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

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

Παραδόξως βοηθά επίσης τον κωδικοποιητή

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

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

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

Τι κάνει για καλή τεκμηρίωση?

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

1. Μην υποθέτετε ποτέ

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

Εάν δημιουργήσατε ένα plugin jQuery, για παράδειγμα, μπορείτε να εμπνευστείτε από την τεκμηρίωση του SlickJS. Δείχνει πώς να δομήσει το HTML, πού να βάλει το CSS και το JavaScript, πώς να προετοιμάσει το plugin jQuery στο πιο βασικό του επίπεδο και ακόμα δείχνει την πλήρη τελική σήμανση μετά την προσθήκη όλων αυτών των στοιχείων, κάτι που είναι κάτι προφανές.

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

2. Ακολουθήστε το πρότυπο

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

 / ** * Προσθέτει προσαρμοσμένες κλάσεις στη σειρά κλάσεων σώματος. * * @param array classes classes για το στοιχείο του σώματος. * @return array * / function body_classes ($ classes) // Προσθέτει μια κατηγορία blog-blog σε blogs με περισσότερους από 1 δημοσιευμένους συγγραφείς. αν (is_multi_author ()) $ classes [] = 'group-blog';  επιστροφή $ classes;  add_filter ('body_class', 'body_classes'). 

Τα παρακάτω είναι μερικά παραδείγματα για τη μορφοποίηση της τεκμηρίωσης inline με τις βέλτιστες πρακτικές σε PHP, JavaScript και CSS:

• PHP: Πρότυπο τεκμηρίωσης PHP για WordPress
• JavaScript: ΧρήσηJSDoc
• CSS: CSSDoc

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

3. Γραφικά στοιχεία

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

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

4. Τμηματοποίηση

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

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

5. Αναθεώρηση και ενημέρωση

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