Il codice può essere la documentazione in strumenti di sviluppo open source? Quanto spesso è?

NHibernate è OSS. È possibile scaricare il codice sorgente gratuitamente, apportare le proprie modifiche, ricompilarlo, reinserire il codice sorgente nel VCS, ecc. Ecc. Ayende richiede di scavare attraverso il codice e quello di DynamicProxy di Castle, per poter utilizzare in modo efficace la sua libreria per implementare il tuo livello di persistenza? Ovviamente no. La community di NHibernate fornisce un insieme di documentazione e buone pratiche per l'utilizzo della libreria NHibernate. Allo stesso modo, l'add-on Fluent NH ha una documentazione decente; non devi scavare nel codice della biblioteca per capire cosa fa e come usarlo.

In breve, anche l'OSS dovrebbe conformarsi al "principio della scatola nera" dal punto di vista dell'utente finale.

I codificatori si aspettano che le loro librerie siano impacchettate come le loro apparecchiature elettroniche: si aspettano di ricevere un manuale di istruzioni insieme a questa "scatola nera", che dice loro come collegarlo e come comunicare con esso. Se non ricevono un manuale, il più intelligente tra loro esaminerà ciò che entra nel pacchetto, si aspetterà di vedere etichette molto chiare per il punto in cui le cose si collegano ad esso, e non assumerà alcuna conoscenza specialistica richiesta per il funzionamento una volta è impostato correttamente. Se nessuno di questi è vero, il programmatore probabilmente chiamerà gli sviluppatori della biblioteca come aiuto, proprio come se tu avessi il supporto tecnico se non avessi tutte le informazioni necessarie per configurare TiVo. La ultima cosa che faresti è spezzare il sigillo su un pezzo di equipaggiamento nuovo di zecca e provare a tracciarlo da sé, proprio come l'ultima cosa che farebbe il programmatore è tirare su e tracciare il codice sorgente della biblioteca per un indizio sul suo funzionamento interno.

Allo stesso modo, i progetti OSS che non sono documentati in modo efficace in altro modo rispetto al codice rientrano in una delle tre categorie:

• progetti per bambini - la documentazione è semplicemente non ancora ben sviluppata perché l'attenzione si concentra su un proof-of-concept e quindi su un codice funzionante. Gli utenti del codice in questa fase sono tester "beta" e comprendono la sua natura "così com'è" su tutti i fronti inclusa la documentazione.
• estremamente semplice - lo scopo dichiarato della libreria, i nomi e le firme delle classi e dei membri della classe visualizzati da qualche browser degli oggetti o JavaDocing the JAR, più forse una semplice demo, dire all'utente tutti loro bisogno di sapere.
• morto o morente - nessuno vuole prendersi il tempo per capire come utilizzare la libreria per tentativi, o per ispezione, quindi nessuno la sta usando.

Il codice sorgente non è una documentazione.

Ho visto troppi (eccellenti) progetti senza documentazione, solo codice sorgente e alcuni tutorial. Il mio ultimo esempio è Lutece (un CMS francese: ho passato molto tempo a capire come usarlo e cosa posso fare con esso. È stato orribile).

Idealmente, la documentazione dovrebbe essere scritta durante lo sviluppo della tua applicazione. Sfortunatamente, molte persone non scrivono alcuna documentazione (non Javadoc per progetti Java, ...), e pensano che i contributori scriveranno tutorial, wiki, documentazioni. Se non c'è una documentazione iniziale, nessuno cercherà di aiutarti, né scoprire il tuo lavoro.

Se riesci a creare una buona documentazione e se hai tempo sufficiente, fallo, fallo;)

No, non penso che il codice dovrebbe essere documentazione. E non credo che importi molto se sia o meno un progetto open source.

Una mancanza di documentazione (diversa dal codice stesso) sarà una svolta per molti potenziali utenti e collaboratori. Ho abbandonato o evitato di utilizzare alcune librerie per altre librerie open-source semplicemente perché i tutorial molto scarsi erano troppo semplicistici (gli usi aziendali reali erano più complessi e richiedevano funzioni che non erano mai chiaramente spiegate o documentate) e la documentazione dell'API ammontava a poco più di function: SetParamX() - This sets param X . Il codice da solo non consente di acquisire facilmente requisiti o specifiche aziendali di livello superiore, ad esempio param X must be a valid subnet mask, unless param Y is set to "foo" . Per dedurre questo requisito, potresti dover leggere 100 righe di codice e passare attraverso 3 o 4 livelli di chiamate al metodo per scoprire esattamente quale sia questo requisito.

Quanto vorresti tu essere a lavorare su un progetto che decifri te stesso solo dal codice? So che non lo farei, che si tratti di un progetto open source o di qualche progetto aziendale interno. Almeno con progetti interni (almeno qui), questo è raramente ma non mai) un problema - e se ha capita con un progetto interno, probabilmente potrei trovare la persona che ha scritto il codice e chiedere loro domande.

La documentazione delle parole significa molte cose e per la maggior parte dei progetti open source è un problema.

Pur lasciando da parte molti dettagli, lo classificherei principalmente in tre parti:

1. Documentazione per l'utente finale - dove è probabile che le persone utilizzino solo il prodotto finale. Di gran lunga il più comune e minimo che si trova nei progetti OSS è 'man page'.

2. Documentazione API - qui si assume che le persone guardino all'interno dei moduli, ma solo come una scatola nera, principalmente collegando le librerie. (ad esempio, utilizza una libreria di codec video per creare il tuo lettore multimediale). Uno degli esempi eccellenti è la documentazione GNOME, GTK per gli sviluppatori di applicazioni.

3. Documentazione per gli sviluppatori: qui si presuppone che le persone contribuiranno effettivamente alla logica interna principale per migliorarla o ridimensionarla.

La necessità e il metodo per creare tutti e tre i tipi di documentazione sono diversi.

• La documentazione a livello di utente finale non può certamente essere eseguita all'interno del codice. In genere si tratta di documenti esterni come il manuale utente; non possono essere all'interno del codice (anche se sono trasportati all'interno del tar.gz dei codici sorgente).

• La documentazione dell'API può spesso essere eseguita (e di solito eseguita meglio) utilizzando il tipo di framework doxygen, dove i commenti sopra le funzioni possono essere tradotti in pagine completamente formattate. In questo modo, gli sforzi di formattazione vengono salvati e viene raggiunta la coerenza, mentre i dettagli di base della documentazione sono ancora scritti a mano. Inoltre, possiamo vedere che quando l'API si evolve o diventa non compatibile, la modifica dei commenti può aiutare a rendere più semplice la documentazione della nuova versione. Un'altra cosa che ho visto è scrivere un piccolo file "api_example.c" che spiega come usarlo. Per la maggior parte dei progetti di medie dimensioni è sufficiente.

• Ultimo ma più importante è la documentazione di progettazione che spiega il funzionamento interno del codice. Difficile da dire, ma questo è raro anche nelle aziende professionalmente retribuite. Molte aziende preferiscono creare "documenti di progettazione" da qualche parte al di fuori del codice, ma sfortunatamente man mano che il codice si evolve, questi rimangono scollegati dai documenti. In tale scenario, avendo molti commenti e commenti in cima ai commenti effettivamente aiutano molto meglio. Di solito NON è completo - ma molto spesso, se lo sviluppatore è abbastanza intelligente, ciò che conta davvero è commentare tutte le parti non ovvie in abbondanza. Questo approccio funziona sempre molto meglio.

Tenendo questo in mente - si dovrebbe prestare attenzione alla bozza di documenti di livello superiore solo per spiegare la terminologia e una logica di business più ampia e lasciare i dettagli spiegati all'interno del codice (e lasciarlo evolvere insieme al codice). I documenti esterni quasi sempre mai si evolvono velocemente come il codice, quindi dovrebbero essere limitati su dipendenze e dettagli.

Dipan.

Se vuoi che il progetto OSS abbia successo, dovresti davvero fornire un'ampia documentazione per gli utenti. La maggior parte dei progetti OSS ha una base di utenti relativamente piccola che si preoccupa di approfondire il codice.

Se non sto contribuendo direttamente al progetto in qualche modo, l'unica volta che guardo il codice sorgente è quando sento che ho scoperto un bug e desidero correggerlo io stesso o notificare il progetto del bug I avevo trovato e dove nel codice sento che il problema è.

Non posso dire quante volte ho valutato un progetto OSS complesso per non trovare alcuna documentazione sostitutiva. Molte volte, se ho un'altra scelta più trasparente, andrò in quella direzione in parte perché non desidero passare giorni di prove ed errori per capire come usarlo, o perché ritengo che il progetto sia troppo "verde" o troppo " amatoriale "per impegnarsi a.

Quasi tutti i popolari pacchetti Java OSS che ho usato sono stati ben documentati con javadocs. Per essere tecnici significa che il codice sorgente contiene, non è, la documentazione.

In ogni caso, questi sono in genere alcuni dei migliori sistemi documentati che ho usato. Credo che ciò sia dovuto al fatto di conservare i documenti con il codice sorgente, permettendo loro di essere aggiornati in parallelo, quindi di suddividere i documenti in seguito.