Perché non ci sono panoramiche del codice per progetti open source? [chiuso]

Ci sono progetti open source molto complessi là fuori, e per alcuni di loro penso di poter dare dei contributi, e vorrei poterlo fare, ma la barriera all'ingresso è troppo alta per un solo motivo: per cambiare una riga di codice in un grande progetto devi capirlo tutto.

Non hai bisogno di leggere tutto il codice (anche se leggi, non sarà sufficiente) e capire tutto ciò che fa ogni singola riga e perché, perché probabilmente il codice è modulare e compartimentato, quindi ci sono astrazioni in atto, ma anche allora è necessario avere una panoramica del progetto in modo da poter sapere dove sono i moduli, dove un modulo si interfaccia con l'altro, cosa fa esattamente ogni modulo e perché , e in quali directory e file stanno accadendo tutte queste cose.

Sto chiamando questa panoramica del codice , come il nome di una sezione che i progetti open source potrebbero avere nel sito Web o nella documentazione che spiega il loro codice agli estranei. Penso che avvantaggerebbe i potenziali contributori , in quanto sarebbero in grado di identificare i luoghi in cui potrebbero costruire, i veri programmatori primari coinvolti, poiché sarebbero in grado di, mentre scrivono tutto, riorganizzare le loro menti e aiutare gli utenti , come farebbero essere d'aiuto per capire e segnalare meglio i bug che riscontrano e forse anche diventare collaboratori.

Ma non ho mai visto una di queste "panoramiche del codice". Perché? Ci sono cose come queste e mi mancano? Cose che fanno lo stesso lavoro che sto descrivendo? O è un'idea completamente inutile, poiché tutti, tranne me, possono capire facilmente progetti con migliaia di righe di codice?

Perché è uno sforzo extra per creare e conservare un documento del genere e troppe persone non comprendono i vantaggi associati.

Molti programmatori non sono bravi scrittori tecnici (sebbene molti lo siano); raramente scrivono documenti strettamente destinati al consumo umano, quindi non hanno pratica e non amano farlo. Scrivere una panoramica del codice richiede tempo che non è possibile spendere per la codifica e il vantaggio iniziale per un progetto è sempre maggiore se si può dire "Supportiamo tutte e tre le varianti di codifica" anziché "Abbiamo spiegazioni davvero accurate del nostro codice!" L'idea che un tale documento attirerà più sviluppatori in modo che a lungo termine venga scritto più codice non è esattamente estranea a loro, ma viene percepita come una scommessa incerta; questo testo farà davvero la differenza tra prendere un collaboratore o no? Se continuo a scrivere codice adesso , fai questa cosa.

Un documento di panoramica del codice può anche far sentire le persone sulla difensiva; è difficile descrivere le decisioni di livello superiore senza sentire il bisogno di giustificarle, e molto spesso le persone prendono decisioni senza un motivo che "suona abbastanza bene" quando in realtà è scritto da solo. C'è anche un effetto correlato a quello sopra citato: poiché l'aggiornamento del testo per adattarlo al cambiamento del codice comporta un ulteriore sforzo, questo può scoraggiare ampie modifiche al codice. A volte questa stabilità è una buona cosa, ma se il codice ha davvero bisogno di una riscrittura di medio livello, si trasforma in una responsabilità.

La dura, dura verità?

La documentazione non viene fatta perché i progetti possono farne a meno.

Anche i progetti open source spesso affrontano una forte concorrenza. La maggior parte di questi progetti non iniziano con spalle larghe, iniziano un'idea brillante, spesso un'idea brillante per un solo uomo.

In quanto tali, non possono permettersi il tempo e i costi di assunzione di documentari umani, anche se si sono offerti di collaborare gratuitamente. Un progetto documentato, infatti, di solito ha subito prima diverse iterazioni iniziali. Spesso inizia con 1-3, forse 5 ragazzi che scrivono la loro nuova idea e la mostrano al mondo come una prova del concetto. Se l'idea si rivela valida, allora i "follower" possono aggiungere, tendono a iniziare a chiedere estensioni, nuove opzioni, traduzioni ... A questo punto il codice è ancora un prototipo, di solito con opzioni e messaggi codificati.

Non tutti i progetti open source vanno oltre questa fase, ma solo quelli che spezzano la "massa critica" necessaria per attirare l'interesse del pubblico. Inoltre, uno degli sviluppatori principianti deve "pensare in grande e lontano" e pianificare espansioni e così via. Potrebbe anche diventare il "evangelista" del progetto e talvolta anche il "project manager" (altre volte sono persone diverse). Questo è un passo necessario per far emergere il progetto, dalla dimostrazione del concetto alla realtà consolidata del settore.

Anche in questo caso, il project manager può scegliere di non creare documentazione.

Un progetto dinamico e in crescita verrebbe al contempo rallentato e la documentazione rimarrebbe davvero indietro rispetto al codice mentre viene migliorata molto duramente, per implementare traduzioni, opzioni, plug-in manager ...

Quello che succede di solito è:

1. Viene realizzato un breve documento introduttivo su ciò che il progetto è e dove sta andando (la famosa "tabella di marcia").
2. Se possibile, viene sviluppata un'API che viene eletta come "codice documentato" rispetto alla maggior parte del codice sottostante.
3. Soprattutto l'API ma anche l'altro codice vengono riformattati e vengono aggiunti commenti speciali "PHPdoc" / "Javadoc" ecc. Offrono un discreto compromesso tra tempo speso e ricompensa: anche un modesto programmatore di solito sa come scrivere una riga descrittiva delle sue funzioni, i parametri vengono anche "auto" documentati e il tutto è legato al suo codice pertinente e quindi evitano la documentazione " desyncing "e in ritardo di sviluppo behing.
4. Molto spesso, viene creato un forum. È un potente social media in cui gli utenti finali e i programmatori possono parlarsi (e tra i loro colleghi, possibilmente in subforum "solo per sviluppatori"). Ciò consente a molte conoscenze di emergere lentamente e di consolidarsi in base alla community (leggi: non grava sul team di sviluppatori) FAQ e HOWTO.
5. In progetti davvero grandi, viene anche prodotta una wiki. Dichiaro "grandi progetti" perché spesso sono quelli con abbastanza follower per creare un wiki (lo fa un dev) e poi riempirlo effettivamente oltre le "ossa nude" (la comunità fa).

I documenti di sintesi come quelli che descrivi sono rari anche su progetti commerciali. Richiedono uno sforzo extra con poco valore per gli sviluppatori. Inoltre, gli sviluppatori tendono a non scrivere documentazione a meno che non sia realmente necessario. Alcuni progetti sono fortunati ad avere membri che sono bravi nella scrittura tecnica e, di conseguenza, hanno una buona documentazione per l'utente. La documentazione per gli sviluppatori, se esiste, è improbabile che venga aggiornata per riflettere le modifiche al codice.

Ogni progetto ben organizzato avrà un albero di directory che è relativamente autoesplicativo. Alcuni progetti documenteranno questa gerarchia e / o i motivi per cui è stata scelta. Molti progetti seguono layout di codice relativamente standard, quindi se ne comprendi uno capirai il layout di altri progetti utilizzando lo stesso layout.

Per modificare una riga di codice è necessaria una conoscenza limitata del codice circostante. Non dovresti mai capire l'intera base di codice per farlo. Se hai un'idea ragionevole del tipo di funzione che viene interrotta, è spesso possibile navigare nella gerarchia di directory piuttosto rapidamente.

Per modificare una riga di codice è necessario comprendere il metodo in cui viene trovata la riga. Se capisci qual è il comportamento previsto del metodo, dovresti essere in grado di apportare modifiche correttive o estensioni della funzionalità.

Per le lingue che forniscono l'ambito, è possibile riformattare i metodi con ambito privato. In tal caso, potrebbe essere necessario modificare i chiamanti, nonché il metodo o i metodi di refactor. Ciò richiede una comprensione più ampia, ma ancora limitata, della base di codice.

Vedi il mio articolo Aggiunta di SHA-2 a tinyca per un esempio di come è possibile apportare tali modifiche. Ho una comprensione estremamente limitata del codice utilizzato per generare l'interfaccia.

Ci sono cose come queste e mi mancano? Cose che fanno lo stesso lavoro che sto descrivendo?

Esiste un libro eccellente chiamato The Architecture of Open Source Applications che fornisce descrizioni dettagliate di una varietà di progetti software open source di alto profilo. Tuttavia, non sono sicuro che riempia esattamente il ruolo che stai immaginando, perché credo che il suo pubblico principale sia destinato a sviluppatori che cercano modelli da seguire durante la creazione delle proprie applicazioni, non nuovi collaboratori ai progetti presentati nel libro (anche se sono sicuro che potrebbe essere utile lì).

Perché ci sono molti più programmatori open source che scrittori tecnici open source.

La documentazione richiede manutenzione e tempo per essere aggiornata. Più ingombrante è la documentazione, più ci vuole. E la documentazione che non è in sincronia con il codice è peggio che inutile: fuorvia e nasconde invece di rivelare.

Una base di codice ben documentata è meglio di una meno documentata, ma la documentazione può facilmente richiedere tanto quanto scrivere il codice in primo luogo. Quindi la tua domanda è: è meglio avere una base di codice ben documentata o una base di codice doppia? Il costo per mantenere aggiornata la documentazione ogni volta che il codice cambia vale i contributi di sviluppatori extra che può o non può portare?

Il codice di spedizione vince. Riducendo la quantità di sforzo messo in cose diverse dal codice di spedizione può rendere più frequente la spedizione del codice ed è più probabile che venga spedito prima che finisca le risorse.

Ciò non significa che le cose oltre alla spedizione siano importanti. La documentazione aggiunge valore al progetto e, con un progetto abbastanza ampio, il costo di interconnessione dell'aggiunta di un altro sviluppatore potrebbe essere di gran lunga superiore rispetto all'aggiunta di un documentatore. E, come notato, la documentazione può aumentare gli investimenti nel progetto (facilitando l'adesione di nuovi programmatori).

Tuttavia, nulla vende come il successo: un progetto che non funziona o che fa qualcosa di interessante raramente attira gli sviluppatori.

La documentazione di una base di codice è una forma di meta-lavoro. Puoi dedicare molto tempo a scrivere documenti fantasiosi che descrivono una base di codice che non ha molto valore, oppure puoi dedicare del tempo a fare cose che i consumatori della tua base di codice desiderano e far valere la tua base di codice.

A volte rendere le cose più difficili rende migliori coloro che svolgono il compito. O a causa di un più alto grado di impegno nel progetto (passare ore e ore a imparare l'architettura) o a causa di pregiudizi di abilità (se sei già un esperto di tecnologia correlata, alzarti alla velocità sarà più veloce, quindi la barriera della mancanza di tale documentazione è meno importante: quindi più esperti si uniscono al team e meno principianti).

Infine, per i motivi sopra indicati, è probabile che gli attuali sviluppatori siano esperti della base di codice. Scrivere tale documentazione non li aiuta a capire molto la base di codice, dato che hanno già le conoscenze, aiuta solo altri sviluppatori. Gran parte dello sviluppo open source si basa sul "graffiare un prurito" che lo sviluppatore ha con il codice: mancanza di documentazione che già dice ciò che lo sviluppatore sa raramente prurito.

Oltre ad essere uno sforzo extra , alcuni progetti open source stanno paralizzando le loro documentazioni di proposito, al fine di ottenere lavori freelance per i loro manutentori (implementare qualcosa o tenere corsi di formazione). Non solo non hanno una panoramica del codice, ma le loro API e tutorial sono cattive o mancano molte cose.

Solo per citarne uno abbastanza popolare: bluez. Buona fortuna a trovare un buon tutorial, oltre a cercare dispositivi vicini.