Κέρδη:
- Δυνατότητα παραγωγής πρόχειρων README, εγγράφων και καταγραφής αλλαγών με βάση το κοινό-στόχο και την πηγή με AI
- Δυνατότητα διαχωρισμού των επιπέδων «τι/πώς» και «γιατί» στην τεκμηρίωση και προσθήκη του «γιατί» ως άνθρωπος
- Επαληθεύστε τα βήματα εγκατάστασης εκτελώντας τα προσωπικά και κάνοντας το έγγραφο μέρος της αλλαγής κώδικα
Το πιο συχνά παραμελημένο αλλά μακροχρόνιο μέρος του λογισμικού είναι η τεκμηρίωση. Ο κώδικας είναι αναγνώσιμος ακόμα και μετά από μήνες. Αυτός που το έγραψε έχει φύγει, το πλαίσιο έχει ξεχαστεί και μένει μόνο αυτό που γράφτηκε. Ένα καλό README (εισαγωγικό έγγραφο που εξηγεί τι είναι ένα έργο και πώς να το εγκαταστήσετε και να το εκτελέσετε), επεξηγηματικά σχόλια κώδικα και μια ενημερωμένη τεκμηρίωση API (μια αναφορά που εξηγεί πώς να χρησιμοποιήσετε μια διεπαφή) καθορίζει άμεσα την ταχύτητα μιας ομάδας. Η τεχνητή νοημοσύνη αφαιρεί μεγάλο μέρος της «κόπωσης κατά τη γραφή» από την τεκμηρίωση — αλλά συνοδεύεται από μια παγίδα: η τεχνητή νοημοσύνη μπορεί να συμπεράνει από τον κώδικα τι κάνει, αλλά συχνά δεν μπορεί να ξέρει γιατί γίνεται με αυτόν τον τρόπο.
Σε αυτή την ενότητα, θα μάθετε πώς να δημιουργείτε README, σχόλιο κώδικα, συμβολοσειρά εγγράφων (μπλοκ σχολίων γραμμένο ανά συνάρτηση/κλάση), έγγραφο API και αρχείο καταγραφής αλλαγών με AI. και πώς να διατηρήσετε ανθρώπινα το πιο πολύτιμο μέρος της τεκμηρίωσης: το «γιατί».
Διάκριση μεταξύ "Τι" και "Γιατί"
Υπάρχουν δύο επίπεδα τεκμηρίωσης. Το πρώτο είναι τι/πώς: "αυτή η συνάρτηση ταξινομεί μια λίστα", "εκτελέστε αυτήν την εντολή για εγκατάσταση". Αυτά μπορούν να εξαχθούν από τον κώδικα και τη δομή. Το AI υπερέχει εδώ. Δεύτερον, γιατί: "γιατί κάναμε αυτήν την υπηρεσία ασύγχρονη και όχι σύγχρονη", "γιατί αυτή η οριακή τιμή είναι 30 δευτερόλεπτα", "γιατί επιλέξαμε αυτήν τη βιβλιοθήκη έναντι της άλλης". Αυτά δεν είναι γραμμένα στον κώδικα. Είναι το προϊόν σχεδιαστικών αποφάσεων, περιορισμών και πόνου του παρελθόντος.
Η τεχνητή νοημοσύνη δεν ξέρει το "γιατί". Στην καλύτερη περίπτωση, κάνει μια λογική εικασία - η οποία είναι επικίνδυνη, επειδή ένας λάθος λόγος είναι χειρότερος από το να μην υπάρχει λόγος. Επομένως, ο καταμερισμός της εργασίας είναι σαφής: η τεχνητή νοημοσύνη συντάσσει το «τι/πώς», προσθέτετε το «γιατί». Το πιο πολύτιμο σχόλιο είναι αυτό που λέει όσα δεν μπορεί να πει ο κώδικας.
Συμβουλή: Μην επαναλάβετε με σχόλιο αυτό που λέει ξεκάθαρα ο ίδιος ο κώδικας (όπως i = i + 1 // αύξηση i κατά ένα). Το AI μερικές φορές παράγει τέτοια περιττά σχόλια. Εξαλείψτε τα και αφιερώστε την ενέργειά σας στα σχόλια «γιατί».
Βήμα προς βήμα: Δημιουργία τεκμηρίωσης με AI
- Προσδιορίστε το κοινό-στόχο. «Ένας προγραμματιστής που μόλις ξεκινά», «η εξωτερική ομάδα που θα χρησιμοποιήσει αυτό το API», «ο μέλλοντας εγώ» — το κοινό δίνει τον τόνο στη γλώσσα και το βάθος.
- Δώσε την πηγή. Προσθέστε τον σχετικό κώδικα, το υπάρχον README, το παράδειγμα χρήσης στη γραμμή εντολών. Ένα έγγραφο χωρίς πηγή είναι μια πρόσκληση για κατασκευή.
- Δομή επιβολής. Τυπικές ενότητες για README (Σκοπός, Εγκατάσταση, Χρήση, Διαμόρφωση, Συνεισφορά), μορφή έργου για συμβολοσειρά εγγράφων.
- Σημειώστε τα κενά "γιατί". Ζητήστε από την τεχνητή νοημοσύνη να επισημαίνει αποφάσεις για τις οποίες δεν γνωρίζει το σκεπτικό ως "απαιτείται σημείωση "γιατί" εδώ". Στη συνέχεια συμπληρώνετε αυτά τα κενά.
- Επαληθεύω. Στην πραγματικότητα εκτελέστε τα βήματα εγκατάστασης. δοκιμάστε το δείγμα κώδικα. Ένα README που δεν λειτουργεί είναι χειρότερο από το καθόλου README.
Τρεις Μίνι Θήκες
Περίπτωση 1 — Το README επιτάχυνε την ενσωμάτωση. Το README ενός εργαλείου ανοιχτού κώδικα έλειπε. Οι νέοι συνεργάτες δυσκολεύτηκαν με την εγκατάσταση κατά μέσο όρο 2 ώρες. Η ομάδα έδωσε τα σενάρια εγκατάστασης και το package.json στην τεχνητή νοημοσύνη και συνέταξε ένα δομημένο README, στη συνέχεια έτρεξε η ίδια τα βήματα σε ένα καθαρό μηχάνημα και πρόσθεσε τις δύο εξαρτήσεις που λείπουν. Ο χρόνος εγκατάστασης για τους επόμενους συνεργάτες μειώθηκε σε 25 λεπτά κατά μέσο όρο.
Περίπτωση 2 — Η φτιαγμένη παγίδα «γιατί». Ένας προγραμματιστής ζήτησε από το AI ένα σχόλιο δίπλα σε μια τιμή χρονικού ορίου (timeout=30). Η τεχνητή νοημοσύνη έγραψε μια λογική αλλά εσφαλμένη αιτιολόγηση "για να ανεχθεί υψηλή καθυστέρηση δικτύου". Ο πραγματικός λόγος ήταν το συμβατικό όριο των 30 δευτερολέπτων μιας μεταγενέστερης υπηρεσίας. Η παρερμηνεία οδήγησε έναν επόμενο προγραμματιστή να αυξήσει άσκοπα την αξία, οδηγώντας σε ένα περιστατικό. Μάθημα: ο κάτοχος του κωδικού πρέπει να επαληθεύσει την αιτιολόγηση.
Περίπτωση 3 — Το πρότυπο Docstring έχει αυτοματοποιηθεί. Μια βοηθητική μονάδα με 40 λειτουργίες δεν είχε συμβολοσειρές εγγράφων. Το AI έλαβε τη μορφή έργου (στυλ Google) και παρήγαγε περιγραφές παραμέτρων, επιστροφών και εξαιρέσεων για κάθε συνάρτηση. Ο προγραμματιστής τα εξέτασε και διόρθωσε μερικές δηλώσεις λανθασμένου τύπου. Η τεκμηρίωση 40 λειτουργιών μειώθηκε από περίπου μισή ημέρα σε μία ώρα.
Τέσσερα αντιγράψιμα πρότυπα
Δομημένο προσχέδιο README:
Κοινό-στόχος: {{π.χ. νέος συνεργάτης}}. Γράψτε ένα προσχέδιο README με βάση τα παρακάτω αρχεία. Ενότητες: Σκοπός, Χαρακτηριστικά, Απαιτήσεις, Εγκατάσταση, Λειτουργία, Διαμόρφωση, Δοκιμή, Συνεισφορά. Εξαγωγή εντολών εγκατάστασης/εκτέλεσης από πραγματικά αρχεία. ΠΡΟΣΑΡΜΟΓΗ. Σημειώστε τα μέρη που δεν είστε σίγουροι με "[VERIFY]". Πηγή: {{package.json / scripts / δείγμα κώδικα}}
Αναφορά εγγράφων/API:
Γράψτε τη συμβολοσειρά εγγράφων σε αυτές τις συναρτήσεις σε μορφή {{στυλ έργου: Google/NumPy/JSDoc}}: σύντομη περίληψη, παράμετροι (τύπος + σημασία), επιστροφή, εξαιρέσεις, 1 σύντομο παράδειγμα. Μην επαναλάβετε αυτό που λέει ΞΕΚΑΘΑΡΑ ο κωδικός. Επισημάνετε τις αποφάσεις σχεδιασμού που απαιτούν το "γιατί" ως "[ΓΙΑΤΙ ΑΠΑΡΑΙΤΗΤΟ]", μην γράφετε μια κατασκευασμένη αιτιολόγηση.{{code}}
Καταργήστε τα κενά για το σχόλιο "γιατί":
Σε αυτόν τον κώδικα, ο επόμενος προγραμματιστής μπορεί να ρωτήσει "γιατί συμβαίνει αυτό;" (μαγικοί αριθμοί, ασυνήθιστες αποφάσεις, λύσεις). Δώστε ένα σχόλιο για το καθένα, αλλά αφήστε το σκεπτικό ΚΕΝΟ. Θα συμπληρώσω την αιτιολόγηση.{{κωδικός}}
Δήλωση Changelog/PR:
Γράψτε μια {{καταχώρηση καταγραφής αλλαγών / περιγραφή δημοσίων σχέσεων}} από την παρακάτω διαφορά. Μορφή: Τι άλλαξε (στη γλώσσα χρήστη), Γιατί (θέμα: {{...}}), Ενδιάμεση αλλαγή (αν υπάρχει), Έχει δοκιμαστεί. Προσαρμόστε την τεχνική ορολογία στο κοινό-στόχο.{{διαφορά}}
Αδύναμη προτροπή / Ισχυρή προτροπή
Αδύναμο: "Γράψε ένα README για αυτό το έργο."
Ισχυρό: "Κοινό-στόχος: ένας προγραμματιστής που κλωνοποιεί αυτό το αποθετήριο για πρώτη φορά. Με βάση το συνημμένο πακέτο.json, το docker-compose.yml και το φάκελο scripts/, γράψτε ένα πρόχειρο README με ενότητες Σκοπός, Απαιτήσεις, Εγκατάσταση, Λειτουργία, Δοκιμή, Συνεισφορά. Εξαγάγετε τις εντολές από αυτά τα αρχεία; ΑΝ βεβαιωθείτε ότι δεν έχετε επισημάνει [ΕΑΝ δεν είστε βέβαιοι] με κανένα αρχείο]."
Η ισχυρή έκδοση δίνει στο κοινό, την πηγή, τη δομή και τον κανόνα «κάντε το, σημαδέψτε το». ώστε το έγγραφο να βασίζεται σε πραγματικά αρχεία και να είναι ευδιάκριτα τα σημεία που πρέπει να επαληθευτούν.
Τύπος εγγράφου
Το AI κάνει καλά
Ο άνθρωπος προσθέτει/επαληθεύει
Εγκατάσταση README
περίγραμμα βημάτων
Εκτελέστε τα βήματα και επιβεβαιώστε
Docstring/API
Δομή, παράμετρος, τύπος
Σωστός τύπος και "γιατί"
Σχόλιο κώδικα
Περίληψη "Τι κάνει".
«Γιατί είναι αυτό» αιτιολόγηση
Changelog/PR
πρώτο σχέδιο
Αντίκτυπος και ακρίβεια
Αρχιτεκτονική απόφαση (ADR)
σκελετός
Πραγματικές αποφάσεις και συμβιβασμούς
Η τεκμηρίωση απαιτεί συντήρηση
Η πιο επικίνδυνη πτυχή ενός εγγράφου είναι όταν φαίνεται αληθινό, παρόλο που είναι ψευδές. Όταν ο κώδικας αλλάζει και το έγγραφο δεν ενημερώνεται, παραπλανά ενεργά τον αναγνώστη. Η τεχνητή νοημοσύνη διευκολύνει την ενημέρωση: εκδώστε μια διαφορά και ρωτήστε "ποια μέρη του εγγράφου επηρεάζει αυτή η αλλαγή;" μπορείτε να ρωτήσετε. Αλλά είναι η διαδικασία που διασφαλίζει την ενημερότητα — κάντε την ενημέρωση της τεκμηρίωσης μέρος της αλλαγής κώδικα (κριτήριο αποδοχής του PR). Το AI επιταχύνει. Η ομάδα χτίζει πειθαρχία.
Προσοχή: Μην δημοσιεύετε χωρίς να επαληθεύσετε τα βήματα εγκατάστασης σε ένα README. Ένα έγγραφο "μάλλον να λειτουργεί" μπορεί να καταστρέψει την πρώτη μέρα ενός νέου προγραμματιστή και να διαβρώσει την εμπιστοσύνη. Εκτελέστε τα βήματα μόνοι σας σε ένα καθαρό περιβάλλον.
Συνήθη λάθη
- Λάβετε το «γιατί» για να ταιριάζει στο AI. Η ψευδής αιτιολόγηση είναι χειρότερη από τη μη αιτιολόγηση. Ο κάτοχος του κώδικα θα πρέπει να γράψει τον λόγο σχεδιασμού.
- Δεν γίνεται επαλήθευση των βημάτων εγκατάστασης. README που δεν λειτουργεί καταστρέφει την εμπιστοσύνη.
- Περιττό σχόλιο που επαναλαμβάνει τον κώδικα. Παράγει θόρυβο, συσκοτίζοντας τις πραγματικές ερμηνείες του «γιατί».
- Χωρίς να προσδιορίζεται το κοινό-στόχος. Ένα έγγραφο που δεν είναι σαφές σε ποιον είναι γραμμένο δεν χρησιμεύει ούτε στον αρχάριο ούτε στον ειδικό.
- Διαχωρισμός της ενημέρωσης από τη διαδικασία. Εάν το έγγραφο δεν ενημερωθεί με τον κωδικό, γίνεται γρήγορα παραπλανητικό.
Συνοπτικά
Η τεχνητή νοημοσύνη αφαιρεί μεγάλο μέρος του μηχανικού φόρτου από την τεκμηρίωση: γρήγορα προσχέδια README, συμβολοσειρά εγγράφων, αναφορά API, καταγραφή αλλαγών και περιγραφές PR. Αλλά δεν μπορεί να ξέρει το «γιατί», που είναι το πιο πολύτιμο στρώμα, και είναι επικίνδυνο να το φτιάξει. Ο καταμερισμός της εργασίας είναι σαφής: η τεχνητή νοημοσύνη παράγει το «τι/πώς», προσθέτετε το «γιατί». Προσδιορίστε το κοινό, παρέχετε πόρους, επιβάλετε δομή, επισημάνετε μέρη που να χωρούν και επαληθεύστε κάθε βήμα εγκατάστασης εκτελώντας το μόνοι σας. Κάντε την τεκμηρίωση αναπόσπαστο μέρος της αλλαγής κώδικα.
Εργασία εφαρμογής
Επιλέξτε μια ενότητα ή ένα μικρό έργο του οποίου η τεκμηρίωση λείπει ή είναι παλιά. Πρώτα δημιουργήστε ένα περίγραμμα από την τεχνητή νοημοσύνη με το πρότυπο "δομημένο σχέδιο README" (ή συμβολοσειρά εγγράφων). Φροντίστε να δώσετε την πηγή και το κοινό-στόχο. Στη συνέχεια, περάστε από κάθε σημείο όπου η τεχνητή νοημοσύνη έχει επισημάνει [VERIFY] ή [WHY NEEDED]: εκτελέστε πραγματικά τα βήματα εγκατάστασης και συμπληρώστε το σχέδιο «γιατί» με τις δικές σας γνώσεις. Σημειώστε πόσα βήματα πρέπει να διορθωθούν και πόσα "γιατί" προσθέσατε.
λίστα ελέγχου
- [ ] Στην τεκμηρίωση, διακρίνω τα επίπεδα «τι/πώς» και «γιατί».
- [ ] Δεν κάνω το AI να συνθέτει το "γιατί", το προσθέτω μόνος μου.
- [ ] Δίνω στην προτροπή το κοινό-στόχο και τα πραγματικά αρχεία προέλευσης.
- [ ] Επαληθεύω τα σημεία [VERIFY] που επισημαίνονται από το AI εκτελώντας τα προσωπικά.
- [ ] Εξαλείφω τα περιττά σχόλια που επαναλαμβάνουν τον κώδικα.
- [ ] Κάνω την ενημέρωση τεκμηρίωσης μέρος της αλλαγής κώδικα.