Programm-Kommentare außerhalb von Quelltexten

visualstudio
Tags: #<Tag:0x00007ff2a986abc0>

#1

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.