Angenommen, ich entwickle ein relativ großes Projekt. Ich habe bereits alle meine Klassen und Funktionen mit Doxygen dokumentiert, aber ich hatte die Idee, auf jede Quellcodedatei einen "Programmierer-Hinweis" zu schreiben.
Die Idee dahinter ist, in Laienbegriffen zu erklären, wie eine bestimmte Klasse funktioniert (und nicht nur warum, wie die meisten Kommentare es tun). Mit anderen Worten, um anderen Programmierern eine andere Sicht auf die Funktionsweise einer Klasse zu geben.
Zum Beispiel:
/*
* 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.
*/
Wäre dies eine gute Möglichkeit, um neuen Programmierern / Mitwirkenden ein umfangreiches Projekt zu erleichtern, damit sie verstehen, wie es funktioniert? Gibt es neben der Beibehaltung eines einheitlichen Codierungsstils und einer einheitlichen Verzeichnisorganisation auch „Standards“ oder Empfehlungen für diese Fälle?