Documentazione del codice: pubblica o non pubblica?

Sono uno di quegli sviluppatori che ha la mentalità secondo cui il codice scritto dovrebbe essere autoesplicativo e leggere come un libro.

TUTTAVIA, durante lo sviluppo del codice della libreria da utilizzare per altre persone, provo a mettere quanta più documentazione possibile nei file di intestazione; il che fa sorgere la domanda: vale la pena documentare metodi non pubblici? Non li useranno direttamente, infatti, non possono. Allo stesso tempo, se distribuisco il codice non elaborato (sebbene, a malincuore), quei metodi non pubblici saranno visibili e potrebbero aver bisogno di essere spiegati.

Sto solo cercando alcuni standard e pratiche che tutti vedete o utilizzate nei vostri viaggi.

Non prenderei mai in considerazione l'omissione della documentazione per gli interni solo perché un "utente finale" non li utilizzerà; la manutenzione del codice è una ragione più che sufficiente per includere commenti sulla documentazione per tutti i componenti, in particolare per gli interni che tendono ad essere la parte più complessa (e spesso mutevole).

Detto questo, potrebbe esserci un caso valido per tenerli limitati al codice sorgente non header (piuttosto che documentato pubblicamente), al fine di mantenere l'astrazione.

Questo è tutto piuttosto soggettivo, intendiamoci.

Ok, aggiungo il mio modo di commentare / documentare anche all'immagine per varietà. La logica è che evito di descrivere le funzioni o le funzioni membro che sono dichiarate lì solo nell'intestazione. Da un lato temo di aggiungere troppo rumore all'header. D'altra parte, la documentazione e la definizione sono più facili da abbinare per il manutentore. Doxygen non si preoccupa in alcun modo e può filtrare i privati ​​se necessario.

Nell'intestazione della classe:

• intestazioni incluse (perché)
• definizioni di classe sempre (scopo e responsabilità)
• le funzioni virtuali pure sempre (contratto completo)
• le funzioni inline a meno che non si ottengano spiegazioni esplicative
• altri tipi dichiarati se non autoesplicativi
• membri di dati statici (perché)
• altri membri dei dati se non autoesplicativi
• le macro se presenti (contratto e perché)

Codice di implementazione in classe:

• dichiarazioni locali allo stesso modo dell'intestazione
• definizioni delle funzioni sempre (contratto completo)
• definizioni delle funzioni membro sempre (contratto completo o riferimento alla radice dell'override virtuale)
• variabili statiche definite se presenti (scopo del perché)

Nell'intestazione del modello:

• quanto sopra unito e
• tipi adatti / non idonei per argomenti template e
• quanto bene viene rilevata staticamente l'idoneità

private:L'all'inizio della sezione privata è tutta la documentazione gli utenti dovrebbero avere bisogno.

La documentazione vale ogni giorno, aiuta a spiegare brevemente casi d'uso e storie. Quanto mai il codice si spiega da sé non può spiegare il business con la stessa facilità con cui poche righe di narrazione. Il codice richiederebbe sicuramente all'utente di seguire la logica oltre a comprendere cosa sta succedendo. :-) I miei 2 centesimi ...

Decisamente!

Quel codice dovrebbe essere auto-documentato è uno slogan per vivere. Tuttavia, direi che il codice privato ha bisogno di tanta documentazione, se non di più, del codice pubblico, perché di solito è qui che si verificano di solito le ipotesi, solo perché il programmatore presume che rimarrà al buio . Quindi, un paio di mesi dopo, quando arriva un bug, passerai il tempo a cercare di ricordare qual è stata l'idea alla base del codice (forse tu stesso).

La documentazione non dovrebbe essere lì come un bel regalo per gli altri. La documentazione, in tutte le sue facce (nomi delle variabili ben scelti, nomi delle classi autocompensanti, codice ben organizzato, metodi adeguatamente segmentati, ecc.) È un dono per chiunque possa entrare in contatto con il tuo codice, incluso te stesso.