Come funziona la spiegazione del codice
La mappa di ciò che si può spiegare, un argomento una conversazione e documenti che restano nel progetto.
Spiegare è la risposta a una domanda che nessuno sa porre bene: «che progetto è questo e come funziona?» Invece di chiedere in giro in una chat e poi cercare la risposta in una conversazione di trecento righe, ottieni un indice di argomenti e da ciascuno un documento a cui si può tornare.
La mappa di ciò che si può spiegare
La prima cosa che vedi nella scheda Progetto → Spiegazioni è l'invito a comporre la mappa. La mappa è l'elenco di ciò che in questo progetto merita una spiegazione: i livelli, i moduli, il flusso dei dati, singoli file. La compone l'Agente, perché solo lui sa cosa c'è nel progetto.
La composizione gira in background e il risultato non è un messaggio in una conversazione, ma un file nel progetto. Non devi essere presente: la mappa compare nell'applicazione da sé appena l'Agente la scrive.
Nella mappa gli argomenti sono in gruppi. Il primo gruppo è quello generale: l'architettura, il progetto, il flusso dei dati. Sono domande che si possono porre senza conoscere un solo file, per questo vengono prime. Le parti concrete stanno sotto.
Il progetto cambia, la mappa no. «Componi di nuovo la mappa» è quindi il pulsante da usare quando il progetto si è mosso: dopo un refactoring più grande una vecchia mappa confonde più di quanto aiuti.
Un argomento, una conversazione
Con un tocco scegli un argomento o più e poi premi Spiega. La risposta non va nella Conversazione principale, ma in una propria, chiamata come l'argomento.
È voluto, non un dettaglio. Chi sta lavorando non vuole la chat inondata da un'esposizione dell'architettura; chi impara il progetto vuole tornare all'argomento, non pescarlo in una chat. In quella conversazione si può inoltre continuare a chiedere, e le domande restano con l'argomento a cui appartengono.
In corso e finite
Sopra la mappa ci sono due sezioni. Gli argomenti in corso sono quelli di cui una conversazione è già avviata. Le spiegazioni finite sono file nel progetto, in docs/explanations/: un argomento, un file.
La differenza tra loro sta in cosa sopravvive. Una conversazione appartiene al Server e dopo un cambio di progetto o una pulizia scompare. Un file nel progetto resta, va in git, e lo legge anche un collega che non ha coden.
Ciò che è già spiegato non viene offerto una seconda volta nella mappa. Se lo fosse, non sapresti se stai continuando o ripartendo da zero.
A cosa serve
- Un progetto nuovo. Componi la mappa, ti fai spiegare il gruppo generale e in venti minuti hai un quadro che altrimenti metteresti insieme in due giorni.
- Codice altrui. Proprio il file che stai per toccare, spiegato prima che tu ci scriva dentro.
- Documentazione che nasce come prodotto secondario. I file in
docs/explanations/sono scritti per essere letti, non per un modello, e restano nel progetto. - La lettura senza connessione. Le spiegazioni finite stanno nello specchio dei Documenti, quindi si aprono anche offline.
Senza connessione
Commissionare una spiegazione senza connessione al Server non si può: dall'altra parte qualcuno deve lavorare. Quelle già salvate si leggono comunque, e l'applicazione lo dice subito invece di lasciare il pulsante senza reazione.
Si è inceppato da qualche altra parte rispetto a quanto c'è qui? Scrivi a support@coden-app.com.