Misalkan saya sedang mengembangkan proyek yang relatif besar. Saya sudah mendokumentasikan semua kelas dan fungsi saya dengan Doxygen, namun, saya punya ide untuk meletakkan "catatan programmer" pada setiap file kode sumber.
Gagasan di balik ini adalah untuk menjelaskan dalam istilah awam bagaimana kelas tertentu bekerja (dan tidak hanya mengapa seperti kebanyakan komentar lakukan). Dengan kata lain, untuk memberi sesama programmer pandangan lain tentang cara kerja kelas.
Sebagai contoh:
/*
* 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.
*/
Apakah ini cara yang baik untuk membuat proyek besar lebih mudah bagi programmer / kontributor baru untuk memahami cara kerjanya? Selain mempertahankan gaya pengkodean yang konsisten dan organisasi direktori 'standar', apakah ada 'standar' atau rekomendasi untuk kasus ini?