Ich suche nach einer ziemlich willkürlichen Antwort, also könnte das eher eine Diskussion sein. Ich frage mich, was die beste Praxis für das Kommentieren meines C # Codes im Sichtstudio ist. Im Moment verwende ich das Triple ///, um das XML zu generieren und benutze Sand Castle, um eine HTML- oder HTML-Datei zu erstellen. Aber mein Problem ist, dass ich Code-Kommentare aus zwei Gründen verwende:
Wie können beide Ziele erreicht werden, ohne sich gegenseitig zu stören, und gleichzeitig eine schnelle Aufgabe zu sein, ohne viel Programmierzeit zu benötigen?
Der beste Rat, den ich Ihnen geben kann, ist:
Kommentieren Sie keinen schlechten Code; schreibe es um!
Wenn Methoden sehr komplex sind, machst du die meiste Zeit etwas falsch (nicht immer, aber sehr nah an immer). Einen lesbaren Code zu schreiben ist schwer, aber es zahlt sich aus, denn gute Kommentare, die du (oder deine Kollegen) ein Jahr später verstehen wirst, sind ebenfalls schwer (und vielleicht sogar noch härter). Wege, um die Dinge klar zu machen, besteht darin, Methoden in kleineren, gut benannten Methoden aufzubrechen und sehr klare Variablennamen zu verwenden.
Ein Buch, das mir sehr geholfen hat, besseren Code zu erstellen, war Robert Martins Clean Code . Wenn Sie es nicht gelesen haben, tun Sie es bitte. Und lassen Sie alle Entwickler in Ihrem Unternehmen es lesen.
Viel Glück.
Verwenden Sie /// Kommentare, um Ihre öffentliche und geschützte API zu dokumentieren. Verwenden Sie <remarks> , um zu beschreiben, wie Ihre API verwendet werden soll. Die Zielgruppe dieser Kommentare sind andere Entwickler, die Ihren Code verwenden.
Verwenden Sie // comments, um Ihren Code zu kommentieren, wenn der Code allein nicht ausreicht, um zu verstehen, was vor sich geht. Das Publikum dieser Kommentare ist vielleicht selbst drei Monate in der Zukunft oder ein anderer Entwickler wird Ihren Code pflegen. Sie können spezielle Kommentare wie TODO oder BUGBUG verwenden, um Codes zu markieren, die Sie erneut aufrufen müssen.
Ich kombiniere beide Kommentarstile - /// für 'public' Dokumentation über Klassen, Methoden, etc, und // für 'private' Kommentare für mich selbst oder die Programmierer, die mir folgen, um zu lesen.
Tags und Links c# visual-studio comments