Wie würde ein Kommentar bei dir aussehen, bei dem Du beschreibst, warum Du die Lösung so und nicht anders implementiert hast?
- Hinweise auf Entwurfsmuster
- Quellen und wichtige Eigenschaften der verwendeten Algorithmen
- Dokumentation von Sachen, deren Gründe sonst schlecht aus dem Code ersichtlich wären.
(zB. Maßnahmen gegen das Auftreten von False Sharing)
- Gründe für Lösungen, wo man sich gegen das intuitive/kanonische Vorgehen entschieden hat.
(zB. Dokumentation für Workarounds bei Fehlern in verwendeten Bibliotheken)
Natürlich kann einiges davon durch Verweise auf weitere Dokumentation ersetzt werden (z.B. im internen Wiki zum Projekt).