Supposons que je développe un projet relativement important. J'ai déjà documenté toutes mes classes et fonctions avec Doxygen, cependant, j'ai eu l'idée de mettre une "note du programmeur" sur chaque fichier de code source.
L'idée derrière ceci est d'expliquer en termes simples comment une classe spécifique fonctionne (et pas seulement pourquoi, comme le font la plupart des commentaires). En d'autres termes, donner aux autres programmeurs une autre vision du fonctionnement d'une classe.
Par exemple:
/*
* 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.
*/
Serait-ce un bon moyen de rendre un grand projet plus facile à comprendre pour les nouveaux programmeurs / contributeurs? Outre le maintien d'un style de codage cohérent et d'une organisation de répertoires «standard», existe-t-il des «normes» ou des recommandations pour ces cas?