Scrivi commenti per un piccolo codice con uno sfondo piuttosto grande [duplicato]

Avere una grande sezione di commento che spiega i dettagli di "whys" e "hows" di un complicato algoritmo è una buona idea. Ed è meglio avere vicino al codice, in modo che lo sviluppatore non abbia bisogno di cambiare contesto per leggerlo (anche peggio: passare avanti e indietro tra algoritmo e documento).

Ricorda di includere una sorta di TL; DR in cima al lungo commento, per coloro che hanno bisogno di ottenere solo l'idea / struttura, senza dettagli di implementazione.

P.S. Stavo facendo il porting di un progetto con blocchi di commenti di alcuni mesi fa - sono stati molto utili.

Il codice viene letto molto più spesso di quanto non sia scritto, quindi i commenti scritti con cura valgono il loro peso in oro.

Distilla i dettagli rilevanti dell'articolo a cui fai riferimento mentre scrivi il codice. Includere un URL, anche se potrebbe essere rotto in futuro; c'è sempre l'Internet Archive. E soprattutto, fai riferimenti specifici ai risultati teorici che hai usato, come l'algoritmo di De Casteljau.

Va bene che il codice sia opaco per qualcuno che non ha familiarità con il dominio - in questo caso, spline e analisi numerica - purché il lettore possa trovare riferimenti dettagliati per imparare come capire il codice.

Personalmente mi piace se c'è un commento con informazioni sufficienti per capire il codice. Se lo metti da qualche altra parte, c'è sempre la possibilità che questo si perda fino al momento in cui qualcuno cerca di capire il codice. Comunque, metti un collegamento (potrebbe funzionare, altrimenti è forse nell'archivio web), se ci sono documenti, metti il titolo / gli autori lì in modo che possa essere trovato.

Tuttavia, per qualcuno che conosce il campo, dovrebbe essere sufficiente leggere il commento per capire cosa sta succedendo .

Non so cosa hai fatto esattamente e non hai mai sentito parlare di de Casteljau prima, ma forse qualcosa del genere andrebbe bene:

Splitting the curves into parts because [thats more awesome|i like it|faster›...] using de Casteljau's algorithm.
The following differs from the usual de Casteljau's algorithm:
 a. all control points are cats
 b. we calculate using roman numerals
Maybe a reason why this differs.

A detailed description is at http://pomax.github.io/bezierinfo/#decasteljau
Also the paper "Towards the use of cats as curve points" by "Meow et al." is of great use (link to paper maybe)

If you want, more detailed description

Questo dovrebbe dare abbastanza informazioni per capire il codice o (se non si conosce la teoria dietro di esso) trovare le fonti per la spiegazione.

Gli unici svantaggi dei commenti più lunghi sono la dimensione del file e la necessità per le persone di scorrere il commento. Entrambi non sono un vero problema (la dimensione dei file oggi è importante solo per i sistemi embedded, ecc. E i commenti non sono nei binari, e le persone che si lamentano della necessità di scorrere oltre un commento di 20 righe dovrebbero ottenere un IDE)

Pensa a questo: se qualcuno dovesse cambiare parti di quel codice tra qualche anno, quanto costerebbe all'azienda impiegarlo di più:

1. Ha bisogno di ignorare un grande commento durante la modifica del codice che capisce
2. Ha bisogno di cercare informazioni su come funziona questo codice o addirittura riscriverlo, perché il file che lo descrive nella cartella dei documenti è stato perso e i collegamenti sono morti

Nota: un argomento sul perché la documentazione deve essere pubblicata nel codice è stata creata nella sezione in fondo a questa risposta.

Ti incoraggio a includere i dettagli dell'algoritmo come commento e altro ancora.

Perché questo algoritmo?

Prima di spiegare l'algoritmo stesso, devi prima spiegare perché è stato scelto questo algoritmo, piuttosto che un'alternativa.

La spiegazione può essere semplice come "Useremo le curve di Bezier, non è stata esplorata nessuna altra alternativa dato che si sono comportati abbastanza bene". Tuttavia, se hai provato le alternative, spiega perché sono state respinte.

L'idea qui è che un maintainer che verrà in seguito potrebbe dover di nuovo esplorare (cercando prestazioni o accuratezza migliori ad esempio), e se hai già fatto il lavoro con l'algoritmo X e Y, e i motivi per cui sono stati rifiutati si applicano ancora , quindi il maintainer può decidere di iniziare a controllare un altro algoritmo invece di ripetere i tuoi esperimenti.

Quale algoritmo?

Perché questo potrebbe sembrare sciocco, visto che hai detto "Bezier Curves", ricorda che a volte ci sono lievi variazioni di algoritmi / strutture dati / ... (B-Tree, B + -Tree, B * -Tree per esempio). Pertanto, specificando con la massima precisione possibile quale algoritmo è stato selezionato e da quale fonte è stato estratto (preferibilmente uno disponibile online ...) può aiutare le aspettative dei lettori con la realtà.

Inoltre, se questa è una variante rispetto alla versione generale del libro di testo, assicurati che sia chiaramente etichettata come tale, per timore che i lettori si chiedano perché sembra deviare.

Come funziona questo algoritmo?

Questo dipende molto dalla squadra con cui lavori. Se le curve di Bezier sono il pane e il burro della squadra, allora una semplice fodera potrebbe essere sufficiente; tuttavia se il codice può essere letto / mantenuto da persone per le quali questo suona come una figura di surf, descrivere l'algoritmo suona meglio.

In secondo luogo, un altro vantaggio di descrivere l'algoritmo nei commenti è che rende facile dividere la descrizione, lo stile di programmazione alfabetico. Cioè, per prima cosa inizi con una struttura generale dell'algoritmo che identifica solo le sezioni, e quindi per ogni sezione avrai un blocco di commenti e immediatamente sotto il codice associato. Rende più facile verificare che il codice sia adeguato ai commenti.

Infine, un ultimo vantaggio nel descrivere l'algoritmo nei commenti è che rende possibile annotare l'algoritmo stesso. Puoi prendere scorciatoie (un singolo giro di approssimazione invece di due è sufficiente per le tue esigenze di precisione, ad esempio), o al contrario spiegare perché un dato passo è necessario (e quali sono le conseguenze della sua rimozione); potresti anche correggere l'algoritmo (se hai indicato una versione stampata, ad esempio, potrebbe esserci un errore ...).

Dove?

Poiché questo è un dettaglio di implementazione, non dovrebbe intralciare il chiamante. I dettagli di implementazione devono essere documentati in la funzione (non al di fuori) e, a seconda del generatore di documentazione, utilizzando i commenti "puri" in quanto non è necessario che vengano visualizzati nella documentazione.

Perché documentare in il codice?

Sosterrò che la documentazione del codice dovrebbe vivere il più vicino possibile al codice. Il motivo è semplice:

• il sistema di tracciamento dei bug potrebbe cambiare, e anche se lo strumento di importazione funziona, gli ID potrebbero cambiare
• il sistema di controllo del codice sorgente potrebbe cambiare
• il repository potrebbe essere riorganizzato, diviso in più, ecc ...
• ...

Ogni volta che si verifica un evento del genere, esiste il rischio che i collegamenti tra (nuovi) limiti vengano interrotti.

Il codice è l'unica costante !

In effetti:

• senza il codice, non hai bisogno della documentazione
• con il codice, ottieni i commenti e quindi la documentazione all'interno di

Quindi è più probabile che la documentazione sia disponibile se inclusa nel codice.

C'è un limite, ovviamente, per esempio i file di testo non possono contenere immagini, quindi è difficile includere nei commenti grafici / diagrammi (l'ASCII Art non deve essere sottovalutato, e sì, sono serio). Il testo fermo è molto lungo, quindi per lo meno puoi fornire una buona spiegazione e quindi nulla ti impedisce di fornire una spiegazione più approfondita altrove e di collegarti ad esso.

Sembra che tutte le altre risposte siano "mettilo nei commenti!"

Ho intenzione di andare controcorrente e consiglio di tenerlo in un documento separato insieme al codice, per questo motivo: sembra che il tuo codice stia facendo qualcosa che richiede una comprensione matematica complicata. La matematica può essere abbastanza difficile da comprendere nel migliore dei casi; può essere ancora più difficile da capire senza una notazione standard adeguata, e i commenti sul codice non sono un posto molto semplice per mettere una notazione matematica di fantasia. L'arte ASCII può solo farti arrivare così lontano.

Invece, vorrei emettere brevemente l'algoritmo nei commenti del codice e fare riferimento al documento che crei in uno strumento appropriato in grado di visualizzare la matematica elaborata per i dettagli. Assicurarsi che questo documento sia collocato nello stesso repository del codice e archiviarlo in una posizione che difficilmente verrà omessa da eventuali spostamenti futuri del codice da un repository all'altro o da un sistema di controllo versioni a un altro. Queste cose accadono!

Dove lavoro, ogni documento ufficiale associato a un progetto ottiene un numero di parte che può essere utilizzato per recuperare il documento in un secondo momento. Se hai processi simili in cui questa applicazione è in fase di sviluppo, prendi in considerazione la possibilità di ottenere un numero assegnato al documento e di fare riferimento a quel numero nei commenti del codice in modo che sia sempre possibile rintracciare quel documento anche se si perde.

Invece di descrivere il complesso algoritmo nel codice sorgente preferisco aggiungere un riferimento al numero ticket del Bug_tracking_system . Esempio:

 /** Split a Bezier into several parts.
  * See #18864 for details */
 public BezierParts[] splittBezier(Bezier aBezier) {
    ...
 }

18864 è il numero di ticket. Il biglietto ha tutte le informazioni tra cui

• un link http all'algoritmo
• allegato con una copia pdf del "link http all'algoritmo" nel caso in cui il collegamento http scompaia.