Documentazione del codice: pubblico vs non pubblico?

Non prenderei mai in considerazione l'omissione della documentazione per gli interni solo perché un "utente finale" non li utilizzerà; la manutenzione del codice è più che sufficiente per includere commenti di documentazione per tutti componenti, infatti specialmente per 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 intestazione (piuttosto che documentato pubblicamente), al fine di mantenere l'astrazione.

Questo è tutto piuttosto soggettivo, attenzione.

Ok, aggiungo il mio modo di commentare / documentare troppo all'immagine per varietà. La logica è che evito di descrivere funzioni o funzioni membro che sono state dichiarate solo nell'intestazione. Da un lato temo di aggiungere troppo rumore all'intestazione. Sulla documentazione di altra mano insieme alla definizione è più facile per il maintainer abbinare. Doxygen non si cura in alcun modo e può filtrare i dati personali se necessario.

Nell'intestazione della classe:

• intestazioni incluse (perché)
• definizioni di classe sempre (scopo e responsabilità)
• le funzioni pure virtuali sempre (contratto completo)
• le funzioni inline a meno che non ci siano getter auto-esplicativi
• altri tipi dichiarati a meno che non si spieghi da soli
• membri di dati statici (perché)
• altri membri di dati a meno che non si spieghino da soli
• le macro se presenti (contratto e perché)

Nel codice di implementazione della classe:

• dichiarazioni locali allo stesso modo dell'intestazione
• definizioni di funzioni sempre (contratto completo)
• definizioni di funzioni membro sempre (contratto completo o riferimento a root di override virtuale)
• variabili statiche definite se (scopo perché)

Nell'intestazione del modello:

• quanto sopra unito e
• tipi adatti / non adatti per gli argomenti del modello e
• come viene rilevata staticamente l'idoneità

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

La documentazione vale ogni giorno, aiuta a spiegare casi d'uso e storie in modo sintetico. Quanto mai il codice si spiega da sé non è in grado di spiegare l'attività con la stessa facilità con cui poche righe narrano. Il codice richiederebbe sicuramente all'utente di seguire la logica oltre a capire cosa sta succedendo. :-) I miei 2 centesimi ...

Sicuramente!

Quel codice dovrebbe essere autodocumentante è uno slogan da cui vivere. Tuttavia, direi che il codice privato ha bisogno di tanta documentazione, se non di più, del codice pubblico, perché di solito è qui che di solito si verificano le maggiori assunzioni, solo perché il programmatore presume che rimarrà al buio . Quindi, un paio di mesi dopo, quando arriva un insetto, passerai il tempo a cercare di ricordare quale sia 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 di variabili ben scelti, nomi di classi autodocumentanti, codice ben organizzato, metodi adeguatamente segmentati, ecc.) È un regalo per tutti coloro che potrebbero entrare in contatto con il tuo codice, incluso te stesso.