Documentare le decisioni di progettazione nei commenti di codice?

How can I best document a code design decision in my source code?

La risposta dipende dalla tua comprensione di »meglio« e »decisione progettuale«.

Quale decisione di progettazione ho documentato nel codice:

Come per tutti i commenti, mi piace non avere più commenti del necessario per capire cosa sta succedendo nel codice. Durante la lettura del codice, mi aspetto che il codice sia scritto in modo da rendere evidente ciò che sta accadendo. Di conseguenza, documento il mio codice.

Esempio prevenuto avanti:

def calculate_total_of_articles(articles):
...
   return total

In questo contesto, dovrebbe essere chiaro, cosa fa questo codice; calcola il totale di una collezione di articoli. Non sono necessari ulteriori commenti.

Diciamo che c'è un nuovo requisito aziendale, che devia da ciò che ci si potrebbe aspettare necessario - diciamo: se l'articolo abcd è nella lista, uno è gratuito - Vorrei documentare questa deviazione nel codice:

def calculate_total_of_articles(articles):
"""calculates the total, but according to business decision
   https://ourtrackerwahtever.com/issue1234
   one of abcd comes for free
   ...
"""

Spiego

• che cosa è diverso
• perché è diverso
• dove trovare i dettagli / la ragione di tale decisione

Un altro esempio: per esempio, devi ordinare gli articoli per nome. E hai deciso di implementare bubblesort invece di quicksort o qualche altro algoritmo, non lo avrei documentato nel codice. Mi aspetto che il codice sia scritto nel modo in cui è per un motivo. Se ho dei dubbi sulla decisione presa o ho una proposta di miglioramento, chiedo all'autore originale e fornisco la mia proposta su come migliorare. Non mi aspetto un commento come

I know bubblesort is ugly but in this very case it is the best solution

Di solito il contesto dovrebbe essere chiaro perché l'hai fatto.

Should I just add a massive comment at a point I feel is right? I see no advantage in that.

Per me un source file riguarda le istruzioni, che mi dicono che cosa dovrebbe essere fatto o che cosa dovrebbe essere previsto da questo codice. La domanda di perché è secondaria per me: anche se è

voices in my head told me to write the code in this way

Come ho detto sopra: ovviamente le eccezionali aspettative dovrebbero essere documentate - ma in un modo, che non impedisce il flusso di lettura. Motivi potrebbero essere dati altrove. E se il lettore è interessato, potrebbe seguire, ma lei / lui dovrebbe lasciare il contesto di codice di lettura .

Or should I just create a separate file?

Mi sforzo. Quale file potrebbe essere? Potresti farlo in una sezione di documentazione. Ma d'altra parte, come sviluppatore mi aspetto da una documentazione, che mi dice come raggiungere i possibili obiettivi, come usare il codice, ma non un diario segreto del perché hai fatto certe cose.

Più ci penso, più arrivo alla conclusione:

No. Un file separato non è un buon posto, purché sia associato al tuo codice.

tl; dr

Quindi dove documentare ragioni / decisioni?

• Project Wiki

• Progetto (Bug-) tracker

• Pagina del progetto

• Blog del progetto

Questi sono i migliori, se si accetta la premessa di mantenere il codice base libero da cose non correlate alla comprensione del codice ed evitare lunghe spiegazioni.

Direi che dipende dall'ambito della tua descrizione.

Se la tua decisione di progettazione è così dettagliata che è completamente implementata in un singolo metodo, sarebbe opportuno un commento accanto a tale metodo.

Se la tua decisione di progettazione riguarda una singola classe, vorresti documentarla con la classe.

Se il tuo progetto interessa l'intero progetto, dovresti probabilmente inserire la documentazione nel suo file.

In breve, metti la documentazione nel posto in cui è più probabile trovarla .

Se la spiegazione deve essere molto lunga, inserisci un breve riassunto come commento nel codice con un puntatore a quello più dettagliato nei documenti non in linea.

In generale è molto buona prassi rendere il codice del documento stesso il più possibile, cercando di mantenere i commenti al minimo (ma non meno!), perché in questo modo è più facile seguire e con il time code ha una tendenza divergere dai commenti.

Ci sono naturalmente casi in cui ciò non è facile o possibile, e in quei casi devi ricorrere ai commenti per rendere il codice abbastanza chiaro.

Documenta il tuo codice con i commenti della documentazione XML. Ottieni la capacità di estrarre automaticamente i file di documentazione da questi file sorgente in fase di runtime.

I commenti XML possono essere usati per descrivere quale metodo / classe fare.

Alcune supposizioni di architettura di alto livello che puoi inserire nei file README.

Definitivamente documento nel codice sorgente, per il prossimo lettore, anche se tu sono le più probabilità di essere il prossimo lettore. Quando incontri un po 'di logica complicata dopo alcuni anni, ti ringrazierai.