Γιατί οι προγραμματιστές δεν γράφουν τεκμηρίωση;

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

Το γράψιμο είναι δύσκολο

Οι “μηχανικοί λογισμικού” δεν γράφουν γιατί η σαφής γραφή είναι πολύ, ΠΟΛΥ δύσκολη.

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

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

Αυτός είναι ο λόγος για τον οποίο πολλοί άνθρωποι διαφωνούν σχετικά με την αξία των σχολίων στον κώδικα και τα πλεονεκτήματα της αυτο-τεκμηρίωσης κώδικα (ό,τι κι αν σημαίνει αυτό). Ο Kevlin Henney λέει ότι “το να ζητάμε σχόλια γύρω από περίπλοκο κώδικα είναι μάταιο, επειδή περιμένουμε από τους ίδιους ανθρώπους που δεν μπορούσαν να εκφραστούν καθαρά στον κώδικα να εκφραστούν καθαρά και κατανοητά με κείμενο (Αγγλικά)”.

Η μη τεκμηρίωση δεν εμποδίζει την κυκλοφορία

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

Όπως ειπώθηκε και παραπάνω, η συγγραφή είναι πρωτίστως θέμα σκέψης και ανάλυσης. Στα περισσότερα μέρη, η συγγραφή κώδικα μπορεί να γίνει εύκολα. Ένας αποδιοργανωμένος σωρός κλάσεων και μεθόδων στον κώδικα μπορεί να λειτουργήσει - ένας σωρός λέξεων και παραγράφων δεν θα λειτουργήσει. Η γραφή ΠΡΕΠΕΙ να είναι σαφής εάν πρόκειται να είναι χρήσιμη. Ο κώδικας θα γίνει αποδεκτός (σε κάποιο βαθμό) αρκεί να κάνει τη δουλειά του. Και δεδομένου ότι οι περισσότεροι οργανισμοί επικεντρώνονται μόνο στην κυκλοφορία του προϊόντος, αυτό που δεν εμποδίζει την κυκλοφορία αγνοείται.

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

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

Τι γίνεται με τα εργαλεία

Δεν υπάρχει αμφιβολία ότι το σύνολο εργαλείων που χρησιμοποιούνται συνήθως για την τεκμηρίωση λογισμικού σήμερα είναι θλιβερά ανεπαρκή. Δεν σκεφτόμαστε τα έγγραφα ένα-ένα. Σκεφτόμαστε με όρους ιδεών και στόχων συγκεντρώνοντας πολλές έννοιες ταυτόχρονα. Το έγγραφο που προκύπτει είναι μόνο μια εκδήλωση της διαδικασίας σκέψης. Χρειαζόμαστε εργαλεία που μπορούν να μας βοηθήσουν να συγκεντρώνουμε ιδέες διαχρονικά για να λύσουμε το πρόβλημα. Τα Έγγραφα Google, το Confluence, το Markdown είναι όλα κακά εργαλεία για αυτόν τον τύπο γραφής.

Ωστόσο, μια νέα γενιά εργαλείων όπως το Notion και το Roam αντιμετωπίζουν αυτό το πρόβλημα της αξιοποίησης των εργαλείων. Ας ελπίσουμε ότι αυτά θα λειτουργήσουν όπως προβλέπεται και θα βοηθήσουν στη σκέψη που οδηγεί στη συγγραφή.

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

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

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

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

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

• Γράψτε τεκμηρίωση πριν τον κώδικα. Εκτός αν η αλλαγή είναι ασήμαντη, κάθε προγραμματιστής γράφει ένα σημείωμα για το τι πρόκειται να κάνει και το περνάει από την υπόλοιπη ομάδα. Στο τέλος της συζήτησης, η πραγματική συγγραφή κώδικα θα πρέπει να γίνει ασήμαντη.
• Γράψτε απλά. Μην περιπλέκετε το κείμενο, τουλάχιστον μέχρι να γίνει συνήθεια. Τα διαγράμματα, οι φανταχτερές ενότητες κ.λπ. μπορούν να περιμένουν. Γράψτε πολύ απλά για το τι σκεφτήκατε, τι κάνετε και γιατί. Ακόμη και αν το έγγραφο μπορεί να χρησιμεύσει ως βασικός δείκτης για την υπόλοιπη ομάδα τώρα και στο μέλλον, είναι εξαιρετικά πολύτιμο.
• Τεκμηριώστε την απόφαση με τις εναλλακτικές τους - Αντί να τεκμηριώνετε λεπτομερώς την πραγματική υλοποίηση (η οποία μπορεί να αλλάξει με την πάροδο του χρόνου), επικεντρωθείτε στην τεκμηρίωση των επιλογών και του λόγου για τον οποίο έγιναν. Αυτό είναι κάτι που ο κώδικας δεν μπορεί ποτέ να εξηγήσει και ως εκ τούτου η καταγραφή του τον κάνει πολυτιμότερο. Οι λεπτομέρειες μπορούν να τεκμηριωθούν με βάση τον χρόνο που είστε διατεθειμένοι να επενδύσετε.
• Κάντε την αναζητήσιμη - Καμία ποσότητα τεκμηρίωσης δεν θα έχει καμία χρησιμότητα εάν οι χρήστες δεν μπορούν να την βρουν. Χρησιμοποιήστε εργαλεία που υποστηρίζουν την αναζήτηση κειμένου. Αυτός είναι ένας από τους λόγους για τους οποίους δεν μου αρέσουν τα Έγγραφα Google για τεκμηρίωση. Είναι εξαιρετικό για τη συγγραφή, αλλά απλά απαίσιο για τη συνεργασία και την ανακάλυψη της πληροφορίας.
• Παρακολουθήστε τις αλλαγές. Ορισμένοι οργανισμοί χρησιμοποιούν τον έλεγχο εκδόσεων (version control όπως πχ github) για να παρακολουθούν τις αλλαγές στο σχεδιασμό του συστήματος με την πάροδο του χρόνου. Αυτό είναι υπέροχο. Αλλά αν δεν έχετε φτάσει ακόμα εκεί, κρατήστε ένα έγγραφο ανά χαρακτηριστικό και συνεχίστε να βάζετε σε αυτό ενημερώσεις με ημερομηνία, ώστε η εξέλιξη να μπορεί να παρακολουθείται σε ένα μέρος με ελάχιστη ταλαιπωρία.

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

Αρχική δημοσίευση:
https://eiosifidis.blogspot.com/2024/02/giati-oi-programmatistes-den-grafoun-tekmiriosi.html