Documentazione sul codice sorgente con collegamento ipertestuale e [chiuso]

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

Penso che il problema della documentazione collegata sia stato considerato sbagliato quando abbiamo deciso di includere la documentazione dell'utente nel codice sorgente. Come docco fa.

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

I commenti di codice normalmente sono al loro meglio quando sono brevi, super-corti, quindi posso effettivamente leggere il codice che fa le cose senza dover vedere un po 'di perché e come funziona.

I commenti degli utenti sono destinati a persone che tentano di utilizzare la libreria / API e possono includere esempi di utilizzo, spiegazione del motivo per cui è stata implementata in questo modo o istruzioni su come estendere la libreria. Questo tipo di commenti tendono ad essere veramente prolissi.

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

• Più difficile da leggere il codice
• Documentazione non abbastanza flessibile (supponiamo di aver bisogno di due pagine di documentazione usando lo stesso codice di esempio o di avere una pagina di documentazione che necessita di interleave codice da due file sorgente diversi).

Quindi, perché vogliamo averlo nello stesso file? Bene, nessuno vuole che le loro documentazioni non siano sincronizzate dal codice. Ma lo facciamo comunque, e specialmente ora un giorno con il grande successo di Markdown. Quale penso sia sulla strada giusta, ma se cade breve, mooolto corto.

Quando intercaliamo il commento del codice con il commento dell'utente, abbiamo un binding a 2 vie. Questo ci permette di vedere facilmente quale commento corrisponde a quale parte del codice. Possiamo anche vedere se qualche codice non è documentato. Ciò che non offre è un modo per vedere se il commento è aggiornato o meno, e ciò accade molto quando il tuo codice è difficile da leggere (perché la documentazione lo rendeva brutto).

E se invece di avere un legame a 2 vie, abbiamo un modo? Documentazione che punta al codice. Potremmo avere il 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 marcato con alcune aggiunte, e con gli strumenti adeguati, potremmo aggiungere più valore ad esso.

Immagina questo modo unidirezionale con strumenti come grunt (anche con l'attività di controllo). È possibile rilevare quando un file di origine cambia, 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 si perdano e questo è ciò che accadrà quando si separano codice e commenti in documenti separati.

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

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

Possibili svantaggi che vedo:

• Hai bisogno di un editor speciale che implementa questa funzione

• Il codice non è più solo testo, facile da manipolare e commettere su VCS-es

• Hai bisogno di due volte più larghezza dello schermo per lavorare con il codice

Per quanto riguarda i tuoi argomenti:

More source code and more documentation on the screen(s) at once

Ma può essere sconveniente se si desidera visualizzare due file affiancati.

Ability to edit documentation independently of source code (regardless of language?)

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

Write documentation and source code in parallel without merge conflicts

Di nuovo, probabilmente uno svantaggio. Se i tuoi documenti sono profondamente intercalati con il codice, come puoi modificarli in modo indipendente?

Real-time hyperlinked documentation with superior text formatting

Se è nel codice, è già in tempo reale;) Come per i collegamenti ipertestuali, saltare alla definizione è già implementato nella maggior parte degli IDE.

Quasi-real-time machine translation into different natural languages

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

Every line of code can be clearly linked to a task, business requirement, etc.

Questo non sono sicuro di ... Non si può ottenere con i commenti regolari?

Documentation could automatically timestamp when each line of code was written (metrics)

Gli VCS non forniscono già questo tipo di informazioni?

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

In primo luogo, i commenti del doc devono essere accompagnati dal codice: spostarli altrove rende le cose incredibilmente difficili da gestire praticamente per un guadagno zero. Allora, perché preoccuparsi!

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

Al momento puoi incorporare collegamenti ipertestuali nei commenti di codice ed è possibile generare documenti dal codice utilizzando strumenti come Doxygen o Sphinx. Immagino che basterebbe un po 'di estensione per l'editor di codice per supportare meglio questi strumenti.

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

Oltre a ciò che @Bogdan già afferma, vorrei aggiungere alcuni:

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

• La maggior parte degli IDE supporta codice / commenti compressi , con i risultati finali come segue:

  Invecedelnormale:

Rendi il codice più leggibile, nel caso non ti servano i commenti.

Codice sorgente e documentazione il modo in cui dovrebbe essere fatto.

link