Ho visto molti modi diversi per [o non per] commentare il codice, specialmente i pattern sulle descrizioni dei dettagli delle funzioni e dei file.
Mi piacerebbe sapere qual è il modello più utilizzato per farlo [Sono particolarmente interessato ai generatori di documentazione e ai loro modelli]
Numerosi progetti stanno utilizzando Doxygen , e penso che non ti sbagliare a scegliere quello che preferisci. In precedenza sono stato coinvolto in una parte di un progetto molto più grande che ha utilizzato Doxygen durante il processo di compilazione, non sono riuscito a entrare nella parte della generazione di documentazione effettiva della build, ma aggiungere i commenti è stato semplice e diretto.
Se il tuo progetto è di grandi dimensioni con sottosistemi scritti in lingue diverse, Doxygen è utile a causa dei molti linguaggi supportati: C ++, C, Java, Objective-C, Python, IDL (sapori Corba e Microsoft), Fortran , VHDL, PHP, C #, e in una certa misura D.
Gli sviluppatori di Visual Studio tendono a utilizzare /// <summary /> perché oltre a essere in grado di generare un Xml utilizzabile come input per i generatori di documenti, si ottengono anche i tooltip durante lo sviluppo quando si utilizza il metodo / la classe commentati.
Ero abituato a documentare il codice usando questo tipo di strumenti di documentazione automatica (doxygen, javadoc). Tuttavia, mi sembra di trovare che il costo di creare e mantenere questo tipo di documentazione è stato raramente giustificato dai benefici di averlo. Finché gli utenti possono vedere i nomi / tipi dei parametri della funzione.
Preferisco dedicare del tempo a creare / mantenere esempi e documentazione mirata ai compiti (come faccio x?), oltre a una panoramica generale della funzionalità / modello utilizzata dall'API. Questo è particolarmente vero se il codice sorgente di ciò che stai documentando sarà disponibile per gli sviluppatori che lo usano (dato che possono sempre leggere il codice sorgente per risolvere qualsiasi ambiguità).
Un'API ben progettata dovrebbe essere intuitiva e difficile da utilizzare in modo errato una volta comunicati i concetti principali del modello. La documentazione per-metodo / per-classe in realtà non aiuta a comunicare questi concetti (modello) in modo efficace, in quanto è così frammentato. Utilizzando l'approccio per-metodo / per-classe, i tuoi utenti devono già avere familiarità con la tua API prima ancora che siano in grado di cercare nel posto giusto la documentazione di cui hanno bisogno.
Leggi altre domande sui tag documentation