Suppose that I am developing a relatively large project. I have already documented all my classes and functions with Doxygen, however, I had an idea to put a "programmer's notes" on each source code file.
The idea behind this is to explain in layman's terms how a specific class works (and not only why as most comments do). In other words, to give fellow programmers an other-view of how a class works.
/* * 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. */
Would this be a good way to make a large project easier for new programmers/contributors to understand how it works? Aside from maintaining a consistent coding style and 'standard' directory organization, are there any 'standards' or recommendations for these cases?