Was ist praktischer zu kommentieren, die Deklaration (in der Header-Datei) oder die Definition (in der Quelldatei)? Vielleicht sollte ich beides kommentieren oder kommentieren und alles in eine separate Datei schreiben ...
Sie sollten die Headerdatei mit der höchsten Priorität vollständig dokumentieren.
Kommentare in der Definition sollten sich auf Implementierungsdetails konzentrieren, während Headerkommentare sich auf die Schnittstelle konzentrieren sollten.
Eine dritte Quelle der Dokumentation, wie Sie vorgeschlagen haben, ist ebenfalls nützlich. Es sollte das Gesamtkonzept beschreiben.
Ein großes Plus beim Kommentieren von Header-Dateien ist, dass Sie automatisch Dokumentation daraus erstellen können, wenn Sie sich an eine einfache Syntax halten. Sag Hallo zu doxygen !
Hängt davon ab, was der Kommentar sagt und von wem Sie erwarten, dass er es liest.
Ich möchte zur Antwort von ypnos hinzufügen:
Wo Ihre Kommentare hingehen, hängt davon ab, wer Ihr Publikum ist. In diesem Zusammenhang ist es hilfreich, wenn Sie an Ihren Code als Closed-Source-Lösung denken: Betreuer sehen die Implementierung, Kunden / Benutzer sehen nur die Schnittstelle. Wenn der Kommentar für Benutzer notwendig ist, muss er in die Schnittstelle gehen. Wenn der Kommentar nur für die gegebene Implementierung relevant ist, muss er wahrscheinlich nur in die Implementierung gehen (aber nicht unbedingt, abhängig von Ihrer Zielgruppe).