Supponiamo che io stia sviluppando un progetto relativamente grande. Ho già documentato tutte le mie classi e funzioni con Doxygen, tuttavia, ho avuto l'idea di inserire una "nota del programmatore" su ciascun file di codice sorgente.
L'idea alla base di questo è di spiegare in parole povere come una classe specifica funziona (e non solo perché come fanno la maggior parte dei commenti). In altre parole, per dare agli altri programmatori una visione alternativa di come funziona una classe.
Ad esempio:
/*
* PROGRAMMER'S NOTES:
*
* As stated in the documentation, the GamepadManager class
* reads joystick joystick input using SDL and 'parses' SDL events to
* Qt signals.
*
* Most of the code here is about goofing around the joystick mappings.
* We want to avoid having different joystick behaviours between
* operating systems to have a more integrated user experience, since
* we don't want team members to have a bad surprise while
* driving their robots with different laptops.
*
* Unfortunately, we cannot use SDL's GamepadAPI because the robots
* are interested in getting the button/axes numbers, not the "A" or
* "X" button.
*
* To get around this issue, we created a INI file for the most common
* controllers that maps each joystick button/axis to the "standard"
* buttons and axes used by most teams.
*
* We choose to use INI files because we can safely use QSettings
* to read its values and we don't have to worry about having to use
* third-party tools to read other formats.
*/
Sarebbe un buon modo per rendere più semplice un grande progetto per i nuovi programmatori / contributori per capire come funziona? Oltre a mantenere uno stile di codifica coerente e un'organizzazione di directory "standard", ci sono "standard" o raccomandazioni per questi casi?