<div dir="ltr"><div class="gmail_extra">Prima di tutto bella discussione e grazie a tutti coloro che l'hanno arricchita.</div><div class="gmail_extra"><br></div><div class="gmail_extra">Io credo che prima di decidere se un commento è giusto o sbagliato bisogna calarsi nel contesto.</div><div class="gmail_extra"><br></div><div class="gmail_extra">Le best practices possono essere lette e rilette e ma mai capite. A me capita spesso. Secondo me è uno degli arcani del mondo.</div><div class="gmail_extra"><br></div><div class="gmail_extra">Chiediamoci anche come nascono le best practices?</div><div class="gmail_extra">Dall'esperienza dura sul campo? Da un principio di buon senso? Da una idea balzana del un nuovo arrivato?</div><div class="gmail_extra"><br></div><div class="gmail_extra">Se anche il papa mi dicesse di buttarmi dal ponte, prima di buttarmi cercherei dentro di me se fosse giusto oppure no.</div><div class="gmail_extra"><br></div><div class="gmail_extra">Cominciamo dal testo.</div><div class="gmail_extra">Si può leggere la divina commedia senza leggere le note, facendosi portare dallo spirito poetico, oppure la si può leggere e studiare seguendo le note passo passo. E se le note sono interessanti ti danno parecchio in più. (in questo caso le note non sono state scritte dall'autore)</div><div class="gmail_extra"><br></div><div class="gmail_extra">Ma che centra la divina commedia con un programma? nulla e tutto.</div><div class="gmail_extra">Entrambe sono costruite seguendo un linguaggio ed entrambe possono fare dei giri pindarici e machiavellici.</div><div class="gmail_extra"><br></div><div class="gmail_extra">Se potessimo leggere un programma scritto da un Dante Alighieri è probabile che si riuscirebbe difficile a seguirlo ma chissà che bello che sarebbe.</div><div class="gmail_extra"><br></div><div class="gmail_extra">Quindi chi scrive/programma conta. Non è che tutte le regole (o le best practices) valgono a priori.</div><div class="gmail_extra"><br></div><div class="gmail_extra">Tornando al contesto. </div><div class="gmail_extra">La parola "programma" che ho usato poc'anzi, è del tutto generica. Non è che se scriviamo uno script, un videogioco, una web application, un sito web, un prodotto, un framework o una libreria vigono le stesse regole. A parte la finalità che è chiaramente diversa, è diverso il target.</div><div class="gmail_extra"><br></div><div class="gmail_extra">Se scrivo una libreria, significa che qualcuno o anche me stesso la riutilizzerà in futuro. Target programmatori. Come diceva Marco, vai di docstring e doctest soprattutto sulle API pubbliche.</div><div class="gmail_extra"><br></div><div class="gmail_extra">Se scrivo un framework la documentazione a forma di tutorial è la più importante. Almeno per la maggior parte del target. Vedi Django è parecchio utilizzato da programmatori e la sua forza è nei tutorial online, non certo nei commenti del suo codice.</div><div class="gmail_extra">I commenti che sono importanti qui sono quelli che spiegano delle scelte, spesso facendo riferimenti ai ticket o bug segnalati.</div><div class="gmail_extra">Su un framework come Django ad esempio non è che ti metti a commentare i componenti architetturali, perché la maggior parte di essi è già nota dalla documentazione online.</div><div class="gmail_extra">Se volessi studiare il codice dell'orm ad esempio sarebbe più utile un documento architetturale che ti desse un immagine del design.</div><div class="gmail_extra">Non so voi, ma spesso mi capita di andare a spulciare il codice open, e veramente poco spesso mi metto a leggere i commenti che non siano concisi. (e anche non banali come: creo la classe, calcolo il risultato etc...)</div><div class="gmail_extra"><br></div><div class="gmail_extra">Se scrivo un sito web, usando Django, certo non mi metto a commentare il codice, forse una o due classi dove faccio delle scelte, ma la maggior parte dei models, forms, admin, views, sono del tutto standard e non hanno bisogno di commenti.</div><div class="gmail_extra"><br></div><div class="gmail_extra">Il dominio, i modelli, sono del tutto inutili da commentare, meglio scrivere una breve introduzione o un glossario che spieghi il dominio piuttosto che spezzettare il discorso tra una classe e l'altra.</div><div class="gmail_extra"><br></div><div class="gmail_extra">Se scrivo un prodotto, vuol dire che sarà venduto e che dovrò gestire la sua evoluzione per diversi anni, andando dietro a decine o centinaia (magari migliaia) di clienti. Il che significa che la miglior documentazione tecnica sono i test. Inoltre se è un prodotto bisognerà anche scrivere il manuale di utilizzo utente. (ma è un altra storia)</div><div class="gmail_extra"><br></div><div class="gmail_extra">Solitamente se un prodotto o anche un progetto segue un particolare design la documentazione utile è fatta da howto per i novizi. Se un nuovo programmatore entra nel team deve essere in grado di lavorare nel progetto, quindi howto end-to-end che lo seguono passo passo su casi d'uso semplici che gli permettono di capire il complesso e vasto mondo.</div><div class="gmail_extra"><br></div><div class="gmail_extra">In conclusione, i commenti sono importanti, ma non sono l'unica fonte di documentazione. Sono essenziali se il target è un altro programmatore che deve usare la tua libreria. Ma non sono minimamente sufficienti per documentare il ciclo di vita di un prodotto.</div><div class="gmail_extra"><br></div><div class="gmail_extra">Vanno usati con parsimonia, meno commenti che codice almeno un rapporto 1 a 5. (imho)</div><div class="gmail_extra"><br></div><div class="gmail_extra">Inoltre lo so che è difficile, ma cerchiamo di scrivere codice come se fossimo scrittori che aspirano al successo. L'estetica non è importante per un calcolatore ma per un umano si.</div></div>