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


60

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?


7
Intendi un documento di progettazione? Ho visto il raro progetto con una descrizione di ciascun pacchetto, ma di solito è già un'API.
maniaco del cricchetto,

14
Perché? Perché ci sono pochi progetti i cui manutentori vogliono investire lo sforzo di scrivere e conservare documentazione di alta qualità e spesso potrebbero non capirne neanche i vantaggi.
Alex D,

9
La documentazione può essere obsoleta o imprecisa rispetto al comportamento effettivo. Il codice non può. Quindi la maggior parte dei progetti preferisce il codice.
Paul Draper,

5
Inoltre è facile sottovalutare quanto puoi imparare su un progetto se imposti un timer da cucina per 2 ore circa e basta leggerlo (tm).
Kos,

43
Benvenuti nel mondo guidato dalla comunità: se non è fatto, è perché non l'hai fatto :)
mgarciaisaia,

Risposte:


60

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à.


6
Bene, sembra che la risposta sia sì: gnunet.org/gnunet-source-overview
fiatjaf

5
Se vuoi che esista, offriti volontariamente per scriverlo. Il punto centrale dei progetti open source è che le persone possono e devono contribuire a ciò che possono, previo accordo della comunità che valga la pena integrare.
Keshlam,

8
@keshlam - ha senso se sei già un collaboratore del progetto ... ma se sei un potenziale collaboratore che sta cercando di farsi un'idea di base su come funziona il codice, sei la persona peggiore possibile scrivere quel documento ....
Jon Story il

13
@JonStory Il tuo punto è positivo, ma in pratica ho scoperto che talvolta è vero anche il contrario. In alcuni progetti ho finito per scrivere un sacco di documentazione basata sulle note che ho preso mentre imparavo una base di codice non documentata. Era una documentazione migliore perché dovevo iniziare dall'API che potevo vedere e poi scavare sempre più a fondo. Gli sviluppatori che avevano scritto il codice avevano già in mente un modello del codice, e quindi avevano molte ipotesi su ciò che qualcuno avrebbe già saputo. La documentazione di qualcuno che non conosce il progetto può essere una migliore documentazione per qualcuno che non conosce il progetto.
Joshua Taylor,

6
@JonStory: se vieni coinvolto in un progetto non perfettamente documentato, dovrai comunque iniziare a capirlo. Rendere le tue note parte del progetto aiuta a salvare il lavoro della persona successiva. (Non so che qualcuno userebbe la presenza o l'assenza di documenti come fattore decisivo per decidere se contribuire). Il semplice miglioramento dei commenti javadoc (o equivalenti) può essere un modo prezioso per iniziare a contribuire. Seriamente, questo è il principio di base dell'open-source: se vedi qualcosa che deve essere fatto, Fallo invece di aspettare che lo faccia qualcun altro.
Keshlam,

14

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).

2
WOW!! viviamo (e lavoriamo) in due mondi totalmente diversi. Ovunque tu stia attualmente lavorando, esci di lì velocemente e trova un'azienda (ce ne sono molte) in cui viene eseguita correttamente perché in realtà ti fa risparmiare denaro. Non lasciare mai che manager / programmatori di cowboy con la testa a punta provino a dirti diversamente.
Mawg,

6
+1, sono d'accordo con quasi tutti i tuoi punti, l'unica affermazione che rifiuto fortemente è che i parametri vengano documentati "auto" . Quando pensiamo alle spiegazioni piuttosto che ai semplici vincoli di sintassi / tipo, nulla viene "auto-documentato"; un commento generato nello stile Restituisce la X. per un metodo getX non è una documentazione utile, è solo un filler senza ulteriori informazioni.
OR Mapper

3
@Mawg fornire una buona documentazione è un investimento, si rinuncia al tempo degli sviluppatori in cambio di (si spera) più collaboratori in futuro e ad alcuni altri vantaggi. Ma come molti nel suo genere, vale la pena solo se sai che ci sono buone probabilità che il progetto abbia successo e che la maggior parte dei progetti software fallisca. È importante essere consapevoli del pregiudizio alla sopravvivenza quando si lamenta della mancanza di documentazione in progetti di successo.
congusbongus,

Non è possibile che quei progetti falliscano perché non documentano? E per documento intendo piano, in modo che tu capisca, piuttosto che sederti alla tastiera e battere via. Ecco la mia stima per un ciclo di vita del progetto, tutte le cifre +/- 5%. Anticipazioni (requisiti e casi d'uso, architettura, progettazione dettagliata) 50%, codifica dal 10 al 15%, test, il resto. "Se non pianifichi,
prevedi

6

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.


1
Il punto importante qui non è stato quello di affermare quanto è necessario sapere sul codice per apportare una modifica. Naturalmente questo dipenderà da molte cose, ma non avrai mai bisogno di capire l'intero codice, né una panoramica ti darà quella comprensione, ma anche per trovare la linea di codice che cambierai avrai bisogno di una certa conoscenza di la struttura generale del progetto.
fiatjaf,

+1 Non c'è niente di speciale nell'open source. In oltre 10 anni di esperienza nel settore industriale, non ho mai visto un documento di sintesi. Ciò che accade in genere è che i datori di lavoro si aspettano che il primo mese di lavoro abbia una produttività pari a zero perché stai studiando la base di codice. Le "panoramiche" sono di solito implementate nel porre domande ai colleghi
slebetman,

5

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ì).


questo sembra più un commento, vedi Come rispondere
moscerino

4
Non trovo il tuo commento costruttivo. Cosa, in particolare, ritieni manchi? Molte delle altre risposte qui sono lunghe speculazioni sui possibili motivi per cui gli sviluppatori potrebbero non scrivere la documentazione generale. Ho collegato un esempio specifico di buoni documenti generali.
bjmc,

1
Sento che manca una risposta alla domanda posta: "Perché non ci sono panoramiche del codice per progetti open source?"
moscerino

3
Direi che non è possibile rispondere in modo accurato alla domanda scritta quando, in effetti, ci sono panoramiche del codice per alcuni progetti open source. Ho modificato la mia risposta per chiarire che sto rispondendo strettamente a una richiesta di esempi che l'utente potrebbe essersi perso.
bjmc,

1
La domanda scritta è "Ci sono cose come queste e mi mancano?" Questa risposta risponde definitivamente, indicando una raccolta esistente di tali panoramiche del codice. In quanto tale, penso che sia un'ottima (e appropriata) risposta alla domanda.
Jim Garrison,

4

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.


+1 "la documentazione può facilmente richiedere fino a quando la scrittura del codice in primo luogo" - o più a lungo!
Marco,

-1

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.


8
Indipendentemente dal numero di esempi che è possibile elencare per progetti open source male documentati, a mio avviso, l'affermazione che "stanno paralizzando le loro documentazioni di proposito" deve essere supportata da prove conclusive (e anche allora probabilmente non lo considera un dichiarazione generale).
OR Mapper

@ORMapper Iniziamo con "Bluez - il più grande mistero di Linux" . Essendo l'unica libreria bluetooth per Linux, trovo difficile credere che non sia una documentazione perché è uno sforzo extra. Diavolo, c'è doxygen e quanto è difficile scrivere semplici tutorial?
BЈовић,

@ORMapper Poi c'è il kernel Linux. Se ti manca qualcosa (come un driver del kernel), se la tua azienda manca dell'esperienza, puoi assumere qualcuno o trovare un libero professionista o un'azienda che lo farà per te. Quindi, è open source, ma ha un prezzo
BЈовиЈ

@ORMapper Poi ci sono progetti open source, con documentazione in formato cartaceo. Quindi compri un libro e non viene fornita altra documentazione. Questa documentazione è paralizzante o no?
BЈовић,

2
Per quello che vale, ho visto abbastanza trarre profitto dalla documentazione scadente per almeno chiedermi se è intenzionale. Quando gli stessi gruppi che mettono online documentazione a metà sono più che felici di venderti un libro o un corso di formazione, non ci vuole molto cinismo per arrivare a questa conclusione.
cHao,
Utilizzando il nostro sito, riconosci di aver letto e compreso le nostre Informativa sui cookie e Informativa sulla privacy.
Licensed under cc by-sa 3.0 with attribution required.