Guadagni:
- Capacità di produrre bozze README, docstring e changelog in base al pubblico di destinazione e alla fonte con l'intelligenza artificiale
- Possibilità di separare i livelli "cosa/come" e "perché" nella documentazione e aggiungere il "perché" come essere umano
- Verificare i passaggi di installazione eseguendoli personalmente e rendendo il documento parte della modifica del codice
La parte del software più frequentemente trascurata ma di più lunga durata è la documentazione. Il codice è leggibile anche a distanza di mesi; La persona che l'ha scritto non c'è più, il contesto è dimenticato e rimane solo ciò che era scritto. Un buon README (documento introduttivo che spiega cos'è un progetto e come installarlo ed eseguirlo), commenti esplicativi sul codice e una documentazione API aggiornata (un riferimento che spiega come utilizzare un'interfaccia) determinano direttamente la velocità di un team. L'intelligenza artificiale elimina gran parte della "fatica di scrittura" dalla documentazione, ma presenta una trappola: l'intelligenza artificiale può dedurre dal codice cosa fa, ma spesso non può sapere perché viene fatto in quel modo.
In questa unità imparerai come produrre README, commenti sul codice, docstring (blocchi di commenti scritti per funzione/classe), documenti API e log delle modifiche con l'intelligenza artificiale; e come conservare umanamente la parte più preziosa della documentazione: il “perché”.
Distinzione tra "Cosa" e "Perché"
Esistono due livelli di documentazione. Il primo è cosa/come: "questa funzione ordina un elenco", "esegui questo comando per installare". Questi possono essere estratti dal codice e dalla struttura; L’intelligenza artificiale eccelle qui. In secondo luogo, perché: "perché abbiamo reso questo servizio asincrono anziché sincrono", "perché questo valore limite è 30 secondi", "perché abbiamo scelto questa libreria rispetto ad un'altra". Questi non sono scritti nel codice; È il prodotto di decisioni progettuali, vincoli e sofferenze passate.
L'intelligenza artificiale non sa "perché"; Nella migliore delle ipotesi, costituisce un’ipotesi ragionevole, il che è pericoloso, perché una ragione sbagliata è peggiore di nessuna ragione. Quindi la divisione del lavoro è chiara: l’intelligenza artificiale definisce il “cosa/come”, tu aggiungi il “perché”. Il commento più prezioso è quello che dice ciò che il codice non può dire.
Suggerimento: non ripetere con un commento ciò che dice chiaramente il codice stesso (come i = i + 1 // aumenta i di uno). L’intelligenza artificiale a volte produce commenti così ridondanti; Eliminali e dedica le tue energie ai commenti "perché".
Passo dopo passo: generazione di documentazione con l'intelligenza artificiale
- Specificare il pubblico di destinazione. "Uno sviluppatore che ha appena iniziato", "il team esterno che utilizzerà questa API", "il futuro me": il pubblico dà il tono al linguaggio e alla profondità.
- Indica la fonte. Aggiungere al prompt il codice pertinente, il file README esistente e l'esempio di utilizzo. Un documento privo di fonti è un invito alla fabbricazione.
- Struttura di imposizione. Sezioni standard per README (Scopo, Installazione, Utilizzo, Configurazione, Contributo), formato di progetto per docstring.
- Segna gli spazi "perché". Chiedere all'IA di contrassegnare le decisioni di cui non conosce la logica come "qui è richiesta una nota 'perché'"; Quindi riempi quegli spazi vuoti.
- Verificare. Esegui effettivamente i passaggi di installazione; prova il codice di esempio. Un README che non funziona è peggio che non avere alcun README.
Tre mini custodie
Caso 1: onboarding accelerato README. Mancava il README di uno strumento open source; I nuovi contributori hanno avuto difficoltà con l'installazione per una media di 2 ore. Il team ha fornito gli script di installazione e il pacchetto.json ad AI e ha redatto un file README strutturato, quindi ha eseguito i passaggi stessi su una macchina pulita e ha aggiunto le due dipendenze mancanti. Il tempo di installazione per i contributori successivi è sceso a una media di 25 minuti.
Caso 2 – La trappola inventata del “perché”. Uno sviluppatore ha chiesto all'IA un commento accanto a un valore di timeout (timeout=30). L'IA ha scritto una giustificazione ragionevole ma errata "per tollerare un'elevata latenza di rete"; il vero motivo era il limite contrattuale di 30 secondi di un servizio a valle. L'errata interpretazione ha portato uno sviluppatore successivo ad aumentare inutilmente il valore, provocando un incidente. Lezione: il proprietario del codice deve verificare la giustificazione.
Caso 3: lo standard Docstring è diventato automatizzato. Un modulo ausiliario con 40 funzioni non aveva docstring. All'IA è stato fornito il formato del progetto (stile Google) e ha prodotto descrizioni di parametri, resi ed eccezioni per ciascuna funzione; Lo sviluppatore li ha esaminati e ha corretto alcune dichiarazioni di tipo errate. La documentazione di 40 funzioni è passata da circa mezza giornata a un'ora.
Quattro modelli copiabili
Bozza README strutturata:
Pubblico di destinazione: {{ad es. nuovo collaboratore}}.Scrivi una bozza README basata sui file seguenti. Sezioni: Scopo, Funzionalità, Requisiti, Installazione, Funzionamento, Configurazione, Test, Contributo. Estrarre comandi di installazione/esecuzione da file reali; MONTAGGIO. Contrassegna i luoghi di cui non sei sicuro con "[VERIFY]". Fonte: {{package.json/script/codice di esempio}}
Riferimento Docstring/API:
Scrivi una docstring in queste funzioni nel formato {{stile progetto: Google/NumPy/JSDoc}}: breve riepilogo, parametri (tipo + significato), ritorno, eccezioni generate, 1 breve esempio. Non ripetere CHIARAMENTE ciò che dice il codice. Contrassegna le decisioni di progettazione che richiedono "perché" come "[PERCHÉ NECESSARIO]", non scrivere una giustificazione inventata.{{code}}
Rimuovi gli spazi per il commento "perché":
In questo codice, il prossimo sviluppatore potrebbe chiedere "perché è così?" (numeri magici, decisioni insolite, soluzioni alternative). Dai un commento SCHELETRO per ciascuno, ma lascia la motivazione IN BIANCO; Compilarò la giustificazione.{{code}}
Registro delle modifiche/dichiarazione PR:
Scrivi una {{voce del log delle modifiche/descrizione PR}} dal diff qui sotto. Formato: cosa è cambiato (nella lingua dell'utente), perché (problema: {{...}}), modifica sostanziale (se presente), è stato testato. Adatta il gergo tecnico al pubblico di destinazione.{{diff}}
Prompt debole / Prompt forte
Debole: "Scrivi un README per questo progetto."
Forte: "Pubblico target: uno sviluppatore che clona questo repository per la prima volta. Sulla base del package.json, docker-compose.yml e scripts/ cartella allegati, scrivi una bozza README con le sezioni Scopo, Requisiti, Installazione, Operazione, Test, Contributo. Estrai i comandi da questi file, non inventarli; contrassegna i punti in cui non sei sicuro con [VERIFY]."
La versione forte fornisce al pubblico, la fonte, la struttura e la regola "fallo, segnalo"; in modo che il documento sia basato su file reali e i luoghi da verificare siano chiaramente visibili.
Tipo di documento
L'intelligenza artificiale funziona bene
L'essere umano aggiunge/verifica
Installazione README
schema del passo
Esegui i passaggi e conferma
Docstring/API
Struttura, parametro, tipo
Tipo corretto e "perché"
Commento al codice
Riassunto "Cosa sta facendo".
"Perché è questa" la giustificazione
Registro delle modifiche/PR
prima bozza
Impatto e precisione
Decisione architettonica (ADR)
scheletro
Decisioni reali e compromessi
La documentazione richiede manutenzione
L'aspetto più pericoloso di un documento è quando sembra vero anche se è falso. Quando il codice cambia e il documento non viene aggiornato, inganna attivamente il lettore. L'intelligenza artificiale semplifica l'aggiornamento: emetti un diff e chiedi "quali parti del documento influisce su questa modifica?" potresti chiedere. Ma è il processo che garantisce l'aggiornamento: rendere l'aggiornamento della documentazione parte della modifica del codice (criterio di accettazione di PR). L'intelligenza artificiale accelera; La squadra costruisce disciplina.
Attenzione: non pubblicare senza verificare i passaggi di installazione in un file README. Un documento "probabilmente funzionante" può rovinare il primo giorno di un nuovo sviluppatore e minare la fiducia. Esegui tu stesso i passaggi in un ambiente pulito.
Errori comuni
- Ottenere il “perché” per adattarsi all’intelligenza artificiale. Una falsa giustificazione è peggiore di nessuna giustificazione; Il proprietario del codice dovrebbe scrivere il motivo della progettazione.
- Non verificare i passaggi di installazione. README che non funziona distrugge la fiducia.
- Commento non necessario che ripete il codice. Produce rumore, oscurando le reali interpretazioni del "perché".
- Non specificare il pubblico di destinazione. Un documento che non è chiaro a chi sia scritto non è di alcuna utilità né al principiante né all'esperto.
- Separare l'aggiornamento dal processo. Se il documento non viene aggiornato con il codice diventa rapidamente fuorviante.
In sintesi
L'intelligenza artificiale elimina gran parte del carico meccanico dalla documentazione: bozze rapide README, docstring, riferimento API, registro delle modifiche e descrizioni PR. Ma non può conoscere il “perché”, che è lo strato più prezioso, ed è pericoloso inventarlo. La divisione del lavoro è chiara: l’intelligenza artificiale produce il “cosa/come”, tu aggiungi il “perché”. Specifica il pubblico, fornisci risorse, imponi la struttura, contrassegna i luoghi in cui adattarli e verifica ogni passaggio dell'installazione eseguendolo tu stesso. Rendere la documentazione parte integrante della modifica del codice.
Compito dell'applicazione
Scegli un modulo o un piccolo progetto la cui documentazione è mancante o obsoleta. Per prima cosa genera uno schema da AI con il modello "bozza README strutturata" (o docstring); Assicurati di fornire la fonte e il pubblico di destinazione. Quindi ripercorri ogni punto in cui l'IA ha contrassegnato [VERIFY] o [WHY NEEDED]: esegui effettivamente i passaggi di configurazione e compila i "perché" del design con le tue conoscenze. Nota quanti passaggi devono essere corretti e quanti "perché" hai aggiunto.
lista di controllo
- [ ] Nella documentazione distinguo i livelli "cosa/come" e "perché".
- [ ] Non faccio inventare il "perché" dall'intelligenza artificiale, lo aggiungo io stesso.
- [] Fornisco alla richiesta il pubblico di destinazione e i file sorgente effettivi.
- [ ] Verifico i punti [VERIFY] segnati dall'IA eseguendoli personalmente.
- [ ] Elimino i commenti non necessari che ripetono il codice.
- [ ] Sto rendendo l'aggiornamento della documentazione parte della modifica del codice.