Kommentare in Quelltexten sind üblich, wichtig und werden durch Syntax-Highlighting entsprechend schön visualisiert.
Aber was mache ich, wenn ich irgend etwas außerhalb von regulären Quelltext-Dateien kommentieren möchte? Optional sogar noch mit etwas Formatierung, Links und Bildern?
Mein Lösungsansatz
Ich habe mir seit kurzem ein System ausgedacht, das darauf basiert, Markdown-Info-Dateien an beliebigen Stellen im Solution Explorer von Visual Studio anzulegen.
Das sieht dann z. B. so aus:
Ich nenne diese Dateien immer „_info.md“, so dass ich sie leicht wieder finde. Die Dateien können in Projekten, in Ordnern und Unterordnern, und sogar außerhalb von Projekt in Solution-Ordnern liegen (dann jedoch mit eindeutigeren Namen, weil sie physisch alle im gleichen Ordner im Dateisystem liegen).
In den Eigenschaften der Datei habe ich dann „Copy to Output Directory = Do not copy“ eingestellt, weil ich ja nur für mich die Dateien angelegt habe.
Das weiteren habe ich mir die Visual-Studio-Extension „Markdown Editor“ installiert. Diese sorgt dafür, dass die Markdown-Datei beim Öffnen in Visual Studio direkt mit einer Live-Vorschau angezeigt wird.
So kann ich beliebige Inhalte in die Markdown-Dateien schreiben, sogar Bilder darin anzeigen (bevorzugt lade ich diese einfach auf Imgur.com hoch), und mir so meine Inhalte schön formatieren.
Beispiel
Nachfolgend beispielhaft eine kurze Markdown-Datei aus einem Projekt:
Natürlich gilt auch für solche Kommentare in Markdown-Dateien, genau wie in normalen Quelltext-Kommentaren, dass man nicht kommentiert, was passiert, sondern, warum was gemacht wird. Quasi eine Dokumentation der Hintergründe und Design-Entscheidungen.