Perché non ci sono panoramiche di codice per i progetti open-source? [chiuso]

Perché è uno sforzo in più per creare e mantenere un documento del genere e troppe persone non capiscono i benefici associati.

Molti programmatori non sono bravi scrittori tecnici (anche se molti lo sono); raramente scrivono documenti rigorosamente per il consumo umano, quindi non hanno pratica e non amano farlo. Scrivere una panoramica del codice richiede tempo che non puoi spendere per la codifica, e il vantaggio iniziale di un progetto è sempre maggiore se puoi dire "Supportiamo tutte e tre le varianti di codifica" piuttosto che "Abbiamo davvero chiare spiegazioni del nostro codice! " L'idea che un tale documento attirerà più sviluppatori in modo che a lungo termine più codice verrà scritto non è esattamente straniero per loro, ma è percepito come un azzardo azzardo; questo testo farà davvero la differenza tra l'aggirare un collaboratore o no? Se tengo codificato adesso , certamente faremo 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 una ragione che "suona abbastanza bene" quando in realtà è scritto proprio. C'è anche un effetto relativo a quanto sopra: poiché l'aggiornamento del testo per adattarsi al codice che cambia causa uno sforzo ulteriore, questo può scoraggiare cambiamenti radicali nel codice. A volte questa stabilità è una buona cosa, ma se il codice ha davvero bisogno di una riscrittura di medio livello, diventa una responsabilità.

La verità secca e dura?

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

Anche i progetti open source devono spesso affrontare una dura concorrenza. La maggior parte di questi progetti non inizia con le spalle larghe, iniziano un'idea brillante, spesso un'idea brillante per un solo uomo.

Pertanto, non possono permettersi il tempo e i costi per assumere i documentari umani, anche se si offrono di collaborare gratuitamente. Un progetto documentato, infatti, ha di solito attraversato diverse iterazioni iniziali. Spesso inizia con 1-3, forse 5 ragazzi che scrivono la loro idea del romanzo e la mostrano al mondo come una prova di concetto. Se l'idea si dimostra valida, i "follower" possono aggiungere, tendono 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, solo quelli che rompono la "massa critica" necessaria per attirare l'interesse pubblico. Inoltre, uno degli sviluppatori iniziali deve "pensare in grande e lontano" e pianificare espansioni e così via. Potrebbe anche diventare il progetto "evangelista" e talvolta anche "project manager" (altre volte sono persone diverse). Questo è un passo necessario per portare il progetto, dalla dimostrazione del concetto a una realtà consolidata nel settore.

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

Un progetto dinamico e in crescita potrebbe essere rallentato e la documentazione sarebbe davvero in ritardo rispetto al codice mentre viene migliorata molto duramente, per implementare traduzioni, opzioni, plug-in manager ...

Di solito succede:

1. Viene presentato un breve documento introduttivo su ciò che il progetto è e dove andrà (la famosa "tabella di marcia").
2. Se possibile, viene sviluppata un'API e quella viene eletta come "codice documentato" sulla maggior parte del codice sottostante.
3. Soprattutto l'API, ma anche l'altro codice viene riformattato e vengono aggiunti commenti speciali "PHPdoc" / "Javadoc" ecc. Offrono un compromesso accettabile tra il tempo speso e la ricompensa: anche un programmatore modesto di solito sa come scrivere una fodera che descrive le sue funzioni, i parametri vengono anche documentati "auto" e l'intero è legato al codice pertinente e quindi evitano la documentazione " desincronizzare "e ritardare lo sviluppo di behing.
4. Molto spesso, viene creato un forum. È un potente social media in cui utenti finali e programmatori possono parlare tra loro (e tra i loro pari, possibilmente in subforum "solo per sviluppatori"). Ciò consente a un sacco di conoscenze di emergere lentamente e di essere consolidate dalla community (leggi: non pesa sul team degli sviluppatori) FAQ e HOWTO.
5. In progetti davvero grandi, viene anche prodotto un wiki. Io dichiaro "grandi progetti" perché sono spesso quelli con un numero sufficiente di seguaci a creare un wiki (un dev) e in effetti lo riempiono oltre le "ossa nude" (la comunità lo fa).

I documenti di panoramica come quelli che descrivi sono rari anche su progetti commerciali. Richiedono uno sforzo supplementare con scarso valore per gli sviluppatori. Anche gli sviluppatori tendono a non scrivere documentazione a meno che non ne abbiano davvero bisogno. Alcuni progetti sono fortunati ad avere membri che sono bravi in scrittura tecnica, e di conseguenza hanno una buona documentazione utente. La documentazione per gli sviluppatori, se esiste, è improbabile che venga aggiornata per riflettere le modifiche al codice.

Qualsiasi progetto ben organizzato avrà un albero di directory che è relativamente auto-esplicativo. Alcuni progetti documentano questa gerarchia e / o i motivi per cui è stata scelta. Molti progetti seguono schemi di codice relativamente standard, quindi se ne capisci uno capirai il layout di altri progetti usando lo stesso layout.

Per cambiare una riga di codice è necessaria una comprensione limitata del codice circostante. Non dovresti mai capire l'intera base di codice per farlo. Se si ha una ragionevole idea del tipo di funzione che è rotta, è spesso possibile navigare la gerarchia della directory piuttosto rapidamente.

Per cambiare una riga di codice devi capire il metodo con cui la linea viene trovata. 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 eseguire il refactoring dei metodi con ambito privato. In questo caso potrebbe essere necessario cambiare i chiamanti così come il metodo o i metodi del refactoring. Ciò richiede una comprensione più ampia, ma ancora limitata, del codice base.

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

Are there things like these and I'm missing them? Things that do the same job as I am describing?

C'è un libro eccellente chiamato L'architettura delle applicazioni open source che fornisce descrizioni dettagliate di una varietà di alto profilo progetti software open source. Tuttavia, non sono sicuro che soddisfi esattamente il ruolo che stai immaginando, perché credo che il suo pubblico principale sia destinato agli sviluppatori che cercano modelli da seguire quando creano le proprie applicazioni, non nuovi contributori ai progetti presenti nel libro (anche se sono sicuro che potrebbe esservi utile)

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

La documentazione richiede manutenzione e tempo per essere sempre aggiornati. Più la documentazione è voluminosa, più ci vuole. E la documentazione che non è sincronizzata con il codice è peggio che inutile: fuorvia e nasconde invece di rivelare.

Una base di codice ben documentata è migliore di una meno documentata, ma la documentazione può facilmente impiegare il tempo necessario a scrivere il codice. Quindi la tua domanda è, è meglio avere una base di codice ben documentata, o una base di codice che è due volte più grande? Il costo per mantenere aggiornata la documentazione ogni volta che il codice cambia, vale la pena di contribuire con gli sviluppatori aggiuntivi che potrebbe apportare o meno?

Il codice di spedizione vince. Ridurre la quantità di sforzi fatti in cose diverse dal codice di spedizione può far sì che il codice venga spedito più spesso ed è più probabile che venga spedito prima che esaurisca le risorse.

Questo non significa che le cose oltre alla spedizione siano importanti. La documentazione aggiunge valore al progetto e, con un progetto abbastanza grande, il costo di interconnessione dell'aggiunta di un altro sviluppatore potrebbe essere molto più alto rispetto all'aggiunta di un documentor. E, come noto, la documentazione può aumentare gli investimenti nel progetto (rendendo più semplice l'adesione di nuovi programmatori).

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

La documentazione di una base di codice è una forma di meta-lavoro. Puoi dedicare molto tempo alla stesura di fantasiosi documenti che descrivono un codice base che non ha molto valore, oppure puoi dedicare del tempo a fare cose che i consumatori del tuo codice base vogliono e rendere il tuo codice base di valore.

A volte rendere le cose più difficili rende quelli che fanno meglio il compito. O a causa di un maggiore grado di impegno nei confronti del progetto (trascorrendo ore e ore nell'apprendimento dell'architettura) o in base al pregiudizio delle abilità (se sei già un esperto di tecnologia correlata, la 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 le ragioni sopra riportate, gli attuali sviluppatori sono probabilmente esperti nel codice base. Scrivere questa documentazione non aiuta loro a capire molto la base di codice, poiché hanno già le conoscenze, aiuta solo altri sviluppatori. Gran parte dello sviluppo open source si basa su "grattando un prurito" che lo sviluppatore ha con il codice: mancanza di documentazione che già dice ciò che lo sviluppatore sa raramente prurito.

Oltre a un ulteriore sforzo , alcuni progetti open source stanno paralizzando le loro documentazioni di proposito, al fine di ottenere il freelance posti di lavoro per i loro manutentori (per implementare qualcosa o per tenere corsi di formazione). Non solo non hanno una panoramica del codice, ma la loro API e le loro esercitazioni sono pessime o mancano molte cose.

Solo per dirne una abbastanza popolare: bluez. Buona fortuna a trovare un buon tutorial, oltre a cercare i dispositivi nelle vicinanze.