Documentazione del codice sorgente esterna, ipertestuale [chiusa]

Perché incorporiamo ancora le descrizioni in linguaggio naturale del codice sorgente (ovvero il motivo per cui è stata scritta una riga di codice) all'interno del codice sorgente, piuttosto che come documento separato?

Dato l'ampio patrimonio immobiliare offerto ai moderni ambienti di sviluppo (monitor ad alta risoluzione, doppio monitor, ecc.), Un IDE potrebbe fornire pannelli a semiflodo in cui il codice sorgente è visivamente separato da - ma intrinsecamente collegato a - i suoi commenti corrispondenti. Ad esempio, gli sviluppatori potrebbero scrivere commenti sul codice sorgente in un linguaggio di markup hyperlink (collegamento a requisiti software aggiuntivi), che impedirebbe contemporaneamente alla documentazione di ingombrare il codice sorgente.

Quali carenze inibirebbero tale meccanismo di sviluppo del software?

Un modello per chiarire la domanda:

Quando il cursore si trova su una determinata riga nel codice sorgente (mostrato con uno sfondo blu, sopra), viene evidenziata la documentazione che corrisponde alla riga sul cursore (ovvero, distinta dagli altri dettagli). Come notato nella domanda, la documentazione rimarrebbe al passo con il codice sorgente mentre il cursore passa attraverso il codice sorgente. Un tasto di scelta rapida potrebbe alternare tra "modalità documentazione" e "modalità di sviluppo".

I potenziali vantaggi includono:

• Più codice sorgente e più documentazione sugli schermi contemporaneamente
• Possibilità di modificare la documentazione indipendentemente dal codice sorgente (indipendentemente dalla lingua?)
• Scrivi la documentazione e il codice sorgente in parallelo senza unire i conflitti
• Documentazione ipertestuale in tempo reale con una formattazione del testo superiore
• Traduzione automatica quasi in tempo reale in diverse lingue naturali
• Ogni riga di codice può essere chiaramente collegata a un'attività, requisiti aziendali, ecc.
• La documentazione potrebbe automaticamente timestamp quando è stata scritta ogni riga di codice (metriche)
• Inclusione dinamica di diagrammi di architettura, immagini per spiegare le relazioni, ecc.
• Documentazione a fonte singola (ad es. Frammenti di codice tag per l'inclusione manuale dell'utente).

Nota:

• La finestra della documentazione può essere compressa
• Il flusso di lavoro per la visualizzazione o il confronto dei file di origine non sarebbe interessato
• Come avviene l'implementazione è un dettaglio; la documentazione potrebbe essere:
  • mantenuto alla fine del file sorgente;
  • diviso in due file per convenzione ( filename.c, filename.c.doc); o
  • completamente basato su database
• Per documentazione con collegamento ipertestuale, intendo il collegamento a fonti esterne (come StackOverflow o Wikipedia) e documenti interni (ovvero una wiki su un sottodominio che potrebbe fare riferimenti incrociati alla documentazione dei requisiti aziendali) e altri file di origine (simili a JavaDocs).

Discussione correlata: Qual è l'avversione per la documentazione nel settore?

Questo problema mi dà sempre fastidio e ho appena avuto un'idea sulla direzione in cui dovremmo provare a risolverlo (ecco come ho trovato questa domanda).

Penso che il problema relativo alla documentazione collegata sia stato ritenuto errato quando abbiamo deciso di includere la documentazione dell'utente nel codice sorgente. Come fa Docco.

Prima di tutto, consente di differenziare i commenti sul codice dalla documentazione dell'utente.

I commenti sul codice normalmente sono al meglio quando sono brevi, in realtà molto corti, quindi posso effettivamente leggere il codice che fa le cose senza dover vedere qualche poesia sul perché e come funziona.

I commenti degli utenti sono destinati a persone che cercano di utilizzare la tua libreria / API e possono includere esempi di utilizzo, spiegazioni del perché è stata implementata in questo modo o istruzioni su come estendere la libreria. Questo tipo di commenti tende ad essere davvero dettagliato.

Sono d'accordo sul fatto che la documentazione dovrebbe essere scritta in testo semplice, quindi non è riparata dal fornitore ed è facile da aggiungere in un VCS. Ma penso che conservare la documentazione dell'utente nel file sorgente sia stato un grosso errore per almeno due motivi:

• Codice più difficile da leggere
• Documentazione non abbastanza flessibile (supponiamo che io abbia bisogno di due pagine di documentazione usando lo stesso codice di esempio o che abbia una pagina di documentazione che necessita di intercalare il codice da due diversi file sorgente).

Quindi perché vogliamo averlo nello stesso file? Bene, nessuno vuole avere le loro documentazioni fuori sincrono dal codice. Ma lo facciamo comunque, e specialmente ora un giorno con il grande successo di Markdown. Il che penso sia sulla strada giusta, ma se non è all'altezza, va benissimo.

Quando intercaliamo il commento del codice con il commento dell'utente, abbiamo un'associazione a 2 vie. Ciò ci consente di vedere facilmente quale commento corrisponde a quale parte del codice. Possiamo anche vedere se alcuni codici non sono documentati. Ciò che non offre, è un modo per vedere se il commento è aggiornato o meno, e ciò accade molto quando il codice è difficile da leggere (perché la documentazione lo ha reso brutto).

E se invece di avere un'associazione a 2 vie, avessimo una sola via ?. Documentazione che punta al codice. Potremmo avere un codice markdown con comandi speciali come:

Some documentation right here that explains the following code:
   @include_file <path/to/some/file>:<line_start>-<line_end>
or
   @include_file <path/to/some/file>
     @starts_with "some regexp or literal text to search"
     @ends_with "another regexp"
or
   @include_file <path/to/some/file>
     @class MyClass
     @method foo
or any combination or way of linking you could imagine

We can even have semantic in the directives:
   @explain_code <path/and/same/of/above>
   @example_code <path/and/same/of/above>
   @performance_notice <path/and/same/of/above>

Which would do basically the same, but it adds the intention of why
do we want to add this code in the first place, which could be 
used different by an IDE. 

Questo ha il vantaggio di essere markup con alcune aggiunte e con gli strumenti adeguati, potremmo aggiungere più valore ad esso.

Immagina questo legame unidirezionale con strumenti come il grugnito (anche con il compito dell'orologio). È possibile rilevare quando cambia un file di origine, vedere quali file di documentazione dipendono da esso e avvisare l'utente (o contrassegnarlo da qualche parte) se il codice che è stato commentato è cambiato.

404 pagina non trovata

Quando lavori con il codice non vuoi che i tuoi commenti vadano persi ed è quello che succederà quando separerai il codice e i commenti in documenti separati.

Inoltre, mantenere il controllo delle versioni tra il documento di commento e il documento di codice causerà più dolore che guadagno.

Alcuni dei suggerimenti che fai mi piacciono molto, ma potrebbero essere facilmente implementati pur avendo anche codice e commenti in 1 file.

Possibili svantaggi che vedo:

• È necessario un editor speciale che implementa questa funzione

• Il codice non è più solo testo semplice, facile da manipolare e impegnare in VCS-es

• Per lavorare con il codice è necessaria una larghezza dello schermo doppiamente maggiore

Per quanto riguarda i tuoi argomenti:

Più codice sorgente e più documentazione sugli schermi contemporaneamente

Ma può essere scomodo se si desidera visualizzare due file fianco a fianco.

Possibilità di modificare la documentazione indipendentemente dal codice sorgente (indipendentemente dalla lingua?)

Direi che in realtà è uno svantaggio. Personalmente cerco di mantenere la documentazione il più vicino possibile al codice, in modo che non diventi obsoleta.

Scrivi la documentazione e il codice sorgente in parallelo senza unire i conflitti

Ancora una volta, probabilmente uno svantaggio. Se i tuoi documenti sono profondamente interfogliati con il codice, come puoi modificarli in modo indipendente?

Documentazione ipertestuale in tempo reale con una formattazione del testo superiore

Se è nel codice, è già in tempo reale;) Per quanto riguarda i collegamenti ipertestuali, il salto alla definizione è già implementato nella maggior parte degli IDE.

Traduzione automatica quasi in tempo reale in diverse lingue naturali

Non vedo perché non puoi farlo con commenti / docstrings regolari.

Ogni riga di codice può essere chiaramente collegata a un'attività, requisiti aziendali, ecc.

Questo non sono sicuro su ... Non può essere raggiunto con commenti regolari?

La documentazione potrebbe automaticamente timestamp quando è stata scritta ogni riga di codice (metriche)

VCS-es non fornisce già questo tipo di informazioni?

Detto questo, mi piace abbastanza il layout stesso - ma non vedo la necessità di cambiare il formato del file, non è così difficile generarlo da commenti regolari. Ci sono un sacco di generatori di documentazione che lo fanno, ad esempio Docco e i suoi successori, come Pycco o Marginalia .

In primo luogo, i commenti dei documenti devono essere associati al codice: spostarli altrove rende le cose incredibilmente difficili da gestire per un guadagno praticamente pari a zero. Quindi perché preoccuparsi!

Ciò che si potrebbe fare è prendere quei commenti incorporati e nasconderli nell'editor, mostrandoli in una bolla o in una descrizione comando o quant'altro necessario. Spero che un tale approccio possa incoraggiare le persone a scrivere molta più documentazione nel codice, ad esempio una descrizione di una classe potrebbe andare con la classe piuttosto che in un documento di progettazione esterno.

Attualmente è possibile incorporare collegamenti ipertestuali nei commenti sul codice e generare documenti dal codice utilizzando strumenti come Doxygen o Sphinx. Immagino che ci vorrebbe solo qualche estensione di fantasia per l'editor di codice per supportare meglio questi strumenti.

Non collegherei alcuna riga di codice a un bug tracker o a uno strumento di requisiti, è un lavoro migliore per il tuo SCM. Quindi puoi vedere le modifiche al codice per commit che sono collegate a un'attività. Non integrerei nemmeno la documentazione memorizzata nel codice con il tracker dei bug - verrai fregato se avessi mai voluto migrare a uno nuovo (hmm, posso vedere questa funzione essere aggiunta a TFS in questo momento) o se tu perso la cronologia di commit (che succede)

Oltre a quanto già affermato da @Bogdan, aggiungerei alcuni:

• Ho configurato il mio IDE per avere sempre 2 file contemporaneamente. Con la funzione che stai suggerendo, avrei sostanzialmente bisogno di 2 monitor per vedere la stessa quantità di informazioni e 3 per fare quello che sto facendo ora con 2.
• Mentre sfogli un file, non vedi immediatamente i commenti e se non sai esattamente cosa stai cercando, è molto difficile trovarlo.
• Durante la ricerca di un file, non riesco a cercare i commenti direttamente (o altrettanto facilmente).
• A volte ho bisogno di fare vari test / scrivere brevi pezzi di codice sul server live, tramite ssh . Sebbene la funzionalità che stai dicendo potrebbe essere integrata con VIM o altri editor della riga di comando, molto probabilmente ci sarebbero problemi piuttosto grandi

• La maggior parte degli IDE supporta la compressione di codice / commenti , con i risultati finali che sono i seguenti:

  Invece del normale:

  

Rendi il codice più leggibile, nel caso in cui non hai bisogno dei commenti.

Codice sorgente e documentazione come dovrebbe essere fatto.

http://jasmine.github.io/2.3/introduction.html