𝗠𝘆 𝗥𝗘𝗔𝗗𝗠𝗘 𝗦𝗮𝗶𝗱 𝟴𝟬 𝗧𝗼𝗼𝗹𝘀. 𝗠𝘆 𝗖𝗼𝗱𝗲 𝗛𝗮𝗱 𝟵𝟲. 𝗡𝗼𝗯𝗼𝗱𝘆 𝗡𝗼𝘁𝗶𝗰𝗲𝗱 𝗙𝗼𝗿 𝗪𝗲𝗲𝗸𝘀.
Gestisco un progetto open source. Utilizza l'automazione del browser per agenti AI.
Il mio README diceva che il progetto aveva 80 strumenti. Ho inserito quel numero nel tagline, nella navigazione e nei testi per i social media.
La scorsa settimana ho effettuato un audit. Ho confrontato il mio README con il codice effettivo.
Il codice registrava 96 strumenti.
Avevo tre verità diverse in un unico file:
- Il numero di marketing: 80
- L'elenco documentato: 83
- Il codice effettivo: 96
Tredici strumenti erano completamente non documentati. Gli utenti non sapevano che esistessero.
La parte più pericolosa era il divario. Quattro di quegli strumenti non documentati erano strumenti di sistema di alto livello. Utilizzavano eventi a livello di sistema operativo per controllare tastiera e mouse. Questa è la parte più potente e sensibile del mio progetto.
Questo mi ha insegnato una dura lezione sulla deriva della documentazione (documentation drift).
La deriva non è casuale. È influenzata da un bias. Documenti le cose facili e noiose. Ti dimentichi di documentare i nuovi strumenti, quelli potenti o sensibili che rilasci in fretta.
Se vuoi trovare la parte più rischiosa di un progetto, non leggere la documentazione. Guarda il divario tra la documentazione e il codice.
Ho provato a correggere il numero. È stato un errore. Correggere il numero cura solo il sintomo.
Il problema è la manutenzione manuale. Se un essere umano digita un dato, quel dato alla fine diventerà errato.
L'unica vera soluzione è rendere impossibile sbagliare il numero.
Devi derivare i fatti dalla "source of truth".
Il mio progetto aveva già una soluzione: lo smoke test. Il test chiede al server quanti strumenti ha e ne verifica il conteggio. Non utilizza un numero hardcoded. Il test non può mai andare fuori sincrono perché non memorizza mai un numero statico.
Smetti di cercare di essere più disciplinato con la scrittura. La disciplina fallisce. Invece, automatizza i tuoi dati:
- Genera i conteggi utilizzando uno script durante la fase di build.
- Genera gli elenchi degli strumenti direttamente dal registro del tuo codice.
- Usa gli esseri umani solo per la prosa e le spiegazioni.
Se un dato è derivabile, non digitarlo a mano. È solo deriva in attesa di accadere.
Esegui questo audit sul tuo progetto oggi stesso:
- Conta gli elementi reali nel tuo codice.
- Conta ciò che dichiara la tua documentazione.
- Se non coincidono, scopri cosa c'è in quel divario.
Gli elementi nel divario sono solitamente le parti più importanti del tuo progetto.
Community di apprendimento opzionale: https://t.me/GyaanSetuAi