Γιατί έχει σημασία η τεκμηρίωση και γιατί πρέπει να την συμπεριλάβετε στον κωδικό σας

Υπάρχει μια πληθώρα ακρωνύμων όσον αφορά την ανάπτυξη λογισμικού. KISS, DRY, SOLID… και ούτω καθεξής και ούτω καθεξής. Όμως, όταν πρόκειται για τεκμηρίωση ή σχολιασμό του κώδικα σας, δεν υπάρχει απλή φράση.

Γιατί αυτό?

Η τεκμηρίωση πρέπει να είναι εξίσου σημαντική για έναν προγραμματιστή όπως και όλες οι άλλες πτυχές της ανάπτυξης

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

Δεν έχει κανείς χρόνο για αυτό

Ο κύριος λόγος για τον οποίο ο κώδικας δεν έχει έγγραφα είναι λόγω του χρόνου.

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

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

Είναι η λιγότερο μελετημένη λεπτομέρεια που μπορεί να κάνει τη μεγαλύτερη διαφορά στο μέλλον.

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

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

Αν αφιερώσετε αυτόν τον επιπλέον χρόνο για να γράψετε μια σωστή περιγραφή του τι δουλέψατε, θα εξοικονομήσετε τεράστιο χρόνο στο μέλλον.

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

Και τελικά, όταν εσείς, ως προγραμματιστής, πρέπει να καταλάβετε κάτι σχετικά με μια συγκεκριμένη πτυχή της κωδικοποίησης, τι κάνετε;

; Πηγαίνετε στην τεκμηρίωση;

Ο καλός κώδικας δεν χρειάζεται τεκμηρίωση

Ναι, ξέρω, ξέρω… καλά γραμμένος κώδικας, που είναι συνοπτικός και καλά μελετημένος, δεν χρειάζεται να τεκμηριωθεί. Διαβάζει σαν ιστορία .

Παρόλο που μπορεί να είναι έτσι, δεν παραιτείται της ανάγκης για τεκμηρίωση και εδώ είναι ο λόγος:

  1. Είμαστε όλοι εξοικειωμένοι με την ευρωστία του κώδικα που περιλαμβάνει ένα χαρακτηριστικό. Κοιτάζοντας μια ενότητα κώδικα, μπορεί να μην καταστεί σαφές ότι υπάρχουν άλλες ενότητες που συνδέονται βαθιά με αυτόν.
  2. Κάθε υπηρεσία που δημιουργείτε έχει ένα μοναδικό API σε αυτήν. Η σύνταξη του τρόπου χρήσης αυτού του API απαιτεί τεκμηρίωση που μπορεί να διαβαστεί εκτός του κώδικα. Δεν θέλετε να φουσκώσετε την ίδια την τάξη με λεπτομέρειες σχετικά με τον τρόπο χρήσης του API.
  3. Συνεργάτες που εργάζονται σε διαφορετικά τμήματα (που μπορεί να μην είναι προγραμματιστές) μπορεί να θέλουν να κατανοήσουν τι κάνατε και πώς λειτουργεί.
  4. Ακριβώς η ίδια η πράξη μπορεί να σας κάνει να κοιτάξετε διαφορετικά τον κώδικα που γράψατε. Το να εξηγήσετε τι κάνει ο κώδικάς σας θα σας κάνει να εκτιμήσετε την εγκυρότητά του και ίσως να σκεφτείτε να αλλάξετε πράγματα εάν δεν ικανοποιούν τις προσδοκίες σας.
  5. Για χάρη των απογόνων

Πώς να γράψετε καλή τεκμηρίωση

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

  • Κατανοήστε σε ποιον απευθύνεται η τεκμηρίωση. Είναι μόνο για προγραμματιστές; Υπάρχει ευρύτερο κοινό; Η κατανόηση αυτού θα σας εξοικονομήσει χρόνο, καθώς θα γνωρίζετε εκ των προτέρων πόσο πρέπει να επεξεργαστείτε στις εξηγήσεις σας.
  • Γράψτε ένα σύντομο, αλλά περιγραφικό υπόβαθρο, εξηγώντας τα κύρια σημεία αυτού που δημιουργήσατε. Αυτό θα βοηθήσει τους αναγνώστες να κατανοήσουν τον σκοπό της δυνατότητας και να εξακριβώσουν τη συνάφεια της με αυτό που θέλουν να γνωρίζουν.
  • Καταγράψτε και περιγράψτε τις κύριες προοπτικές της δυνατότητάς σας, φροντίζοντας να επισημάνετε τυχόν εξαρτήσεις που υπάρχουν με άλλες λειτουργίες.
  • Βεβαιωθείτε ότι υπάρχει χρονική σήμανση, για να πείτε στους αναγνώστες την εγκυρότητα της τεκμηρίωσης. Επίσης, εάν χρησιμοποιείτε συγκεκριμένες βιβλιοθήκες, φροντίστε να συμπεριλάβετε και τις εκδόσεις τους.
  • Να είστε γενναιόδωροι με τα παραδείγματα κωδικοποίησης, αναφέροντας λεπτομερώς τον τρόπο σωστής χρήσης της δυνατότητας που έχετε γράψει και παρουσιάστε τα αναμενόμενα αποτελέσματα.

Παραδείγματα

Για να κατανοήσουμε περαιτέρω πώς φαίνεται η καλή τεκμηρίωση, θα εξετάσουμε μερικά εξαιρετικά παραδείγματα: το Mozilla's Developer Network (MDN), το Django και το Stripe.

Στην τεκμηρίωση του MDN, μπορείτε να δείτε ξεκάθαρα ότι κάθε σελίδα ξεκινά με μια σύντομη εξήγηση για το θέμα.

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

Η τεκμηρίωση του Django είναι πολύ ισχυρή. Ανεξάρτητα από το επίπεδο κωδικοποίησης, σας ξεκινούν με μια επισκόπηση και σεμινάρια.

Στη συνέχεια, εξετάζουν κάθε θέμα, το αναλύουν σχολαστικά, δίνοντας σύντομα και συνοπτικά αποσπάσματα κώδικα που δείχνουν τι πρέπει να γίνει

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

Ίσως KID - Κ EEP μου t D ocumented;

Αν σας άρεσε αυτό το άρθρο, χτυπήστε το για να το απολαύσουν και άλλοι! ???