È fattibile creare una mini documentazione all'interno del codice sorgente

Questa è la serie di linee guida che ho visto utilizzate in più team:

• Classe: documenta qual è la responsabilità della classe (e solitamente una classe deve avere una sola responsabilità).
• Metodo: documenta cosa va nel metodo, quale metodo usa e cosa esce.
• Codice interno: non documentare ciò che uno sviluppatore può capire sfogliando il codice, piuttosto concentrarsi su ipotesi o cose che sono più difficili da scoprire o una breve spiegazione di una parte di codice complessa.

Ciò impone anche un po 'di design migliore, perché se la classe ha troppe responsabilità, allora c'è un problema. Lo scopo della documentazione è scoprire quando ci si aspetta che le classi e i metodi siano usati senza leggendo il codice. Se qualcuno deve leggere il codice, la documentazione di solito è uno spreco e stai duplicando il codice in inglese.

Utilizziamo pesantemente C #, quindi documentazione del codice C # tag e generazione automatica della documentazione aiuta in modo significativo. Produciamo la documentazione in stile MSDN usando SandCastle e lo mettiamo su una condivisione interna in modo che gli sviluppatori possano guardarlo. Ciò funge da funzione di forzatura. Potresti riuscire a trovare un tale strumento per qualsiasi cosa tu stia lavorando. E mi è stato anche chiesto di scoprire se possiamo anche generare documentazione estratta dal nostro XSD (che è anche documentato in linea usando xs: tag di annotazione).

Infine, se possibile, specialmente per le classi esposte fuori dalla DLL e utilizzate da altre DLL, incoraggio (e personalmente provo ad aggiungere) codice di esempio nei commenti. Questo può essere piuttosto oneroso, soprattutto tenendo a mente l'evoluzione del codice, quindi è qualcosa che non faremo se l'utilizzo può essere trovato guardando altro codice compresi i test.

Suggerirò un approccio diverso per affrontare questo problema.

Suppongo che tu non abbia abbastanza livelli di astrazione e che tu abbia moduli di codice troppo grandi. Prendi in considerazione l'aggiunta di livelli di astrazione e / o oggetti che, con nomi completamente descrittivi, forniscono efficacemente agli sviluppatori che lo leggono con una buona documentazione.

Ad esempio, in Ruby, vedrò frequentemente classi con centinaia di metodi e metodi stessi con migliaia di linee. Frequentemente per la classe dio User. Tale codice, non importa quanto ben scritto, richiederà del tempo per capire. Tuttavia, il refactoring in classi non superiori a 100 linee e metodi non più grandi di 5 righe ("regole di Sandi Metzs") può essere d'aiuto. Quasi ogni volta che refactoring codice con tecniche come Extract Method, Extract Class o affrontare problemi come Too Many Parameters trovo che il codice in seguito sia più facile da leggere.

Puoi avere due buone fonti di documentazione nel tuo codice. Il primo è commenti incorporati che utilizzano un formato standard , come Javadoc o il già citato Tag di documentazione del codice C # . Questi dovrebbero accompagnare ogni classe e ogni metodo che può essere usato da altri (non è necessario farlo con metodi / classi privati, anche se in alcuni casi può essere d'aiuto). Poiché sono un formato standard, molti programmatori hanno già familiarità con loro o possono familiarizzarsi rapidamente con essi. Inoltre, gli strumenti sono in grado di riconoscere ed estrarre i dati da questi blocchi di commenti appositamente formattati. Potresti scrivere Javadoc per un metodo come Math.abs come segue:

/**
 * <p>
 * Returns the absolute value of an int value. If the argument is not negative, the argument is returned. If the argument is negative, the negation of the argument is returned.
 * <p>
 * Note that if the argument is equal to the value of Integer.MIN_VALUE, the most negative representable int value, the result is that same value, which is negative.
 *
 * @param a the argument whose absolute value is to be determined
 * @return the absolute value of the argument.
 */
public static int abs(int a)
{ ...

e utilizzando lo strumento Javadoc integrato di Java, puoi generare qualcosa come questo . Alcuni IDE sono in grado di leggere commenti formattati e fornire documentazione incorporata. Per commenti come questi, è importante concentrarsi sul comportamento, non sull'implementazione. È improbabile che il tuo metodo cambi, ma come può cambiare frequentemente. Concentrarsi su ciò che fa significa meno potenziale di deriva tra commenti e codice.

La seconda fonte di documentazione nel tuo codice sono i tuoi test . Qualcuno dovrebbe essere in grado di capire cosa fanno i tuoi metodi osservando i test. Rspec e altri framework di test guidati dal comportamento sono progettati per essere letti come un linguaggio naturale per ridurre la barriera all'ingresso, ma sono capaci il programmatore può ottenere ciò che è necessario sapere da qualsiasi framework di test valido. Per testare il nostro metodo Math.abs , potremmo avere il seguente test (con JUnit):

@Test
public void testAbs() {
    assertEquals(5, Math.abs(5));
    assertEquals(5, Math.abs(-5));
    assertEquals(0, Math.abs(0));
    assertEquals(Integer.MIN_VALUE, Math.abs(Integer.MIN_VALUE));
}

Da questo test, posso vedere che i valori positivi vengono restituiti così come sono, i valori negativi vengono restituiti negati, zero viene restituito così com'è, e Integer.MIN_VALUE viene restituito così com'è (in conformità con la documentazione che abbiamo scritto per il metodo). Inoltre, se non fossi ancora chiaro su cosa accade per un particolare input (ad esempio Integer.MAX_VALUE ), posso facilmente aggiungere un altro test e scoprirlo, senza interferire con nient'altro. Sebbene i test non siano sempre chiari come i commenti, forniscono verificabilità verificabile. Cioè, posso provare che il codice fa quello che dicono i test eseguendo i test e vedendo che passano. I test generalmente non possono andare alla deriva dal codice come possono fare i commenti, poiché la deriva si manifesterebbe come test non riusciti.

Se ti trovi a dover leggere un sacco di codice solo per scoprire cosa fa un metodo, devi anche fare più sforzi per rendere il tuo codice più auto-documentabile possibile. La classe descrittiva, il metodo e i nomi delle variabili possono migliorare significativamente la leggibilità. Piccoli metodi che puoi trattare essenzialmente come scatole nere (come Math.abs sopra, in cui non conosciamo l'effettiva implementazione) possono anche aiutare a nascondere la complessità dietro un nome più amichevole.

Per lo meno, aggiungi - forse dopo la nota sul copyright - un commento in alcuni paragrafi che descrive il tuo file sorgente. Questo è utile (per le persone future che lavorano sullo stesso codice). Aggiungi anche un file README !

Guarda il codice sorgente dei piccoli progetti di software gratuiti per l'ispirazione!

What should such a minimal documentation contain so it can give a general idea about what the module does and how people can use it?

Niente.

La necessità di documentazione per descrivere ciò che fa il tuo codice è un segno che il tuo codice è mal chiamato, scarsamente strutturato e / o eccessivamente complesso. Certo, ci sono momenti in cui non ci sono buoni nomi, o il codice deve essere complesso perché il problema è complesso. Ma questa è una minoranza in eccesso di qualsiasi base di codice.

In tutta onestà, non leggo più i commenti in cima ai file / classi / metodi (i metodi di nei possono essere comunque utili). I commenti mentono. Si allontanano rapidamente. Il codice può essere fuorviante a causa della scarsa nomenclatura. Il codice può essere fonte di confusione a causa della scarsa strutturazione. Ma il codice non può escludere e mentire su ciò che effettivamente fa.