Kommentare (und Regions) zur optischen Gliederung (z.B. Trennlininen) einsetzen: Best Practice?

Hallo Leute,

ich wollte geren wissen, wie ihr euren fertigen Files aufpeppt. D.h. wo, wie und in welchem Umfang benutzt ihr "Nichtkommentierende Kommentare".

Darunter verstehe ich z.b.:

//==============================================================================

oder

//------------------------------------------------------------------------------

Oder z.b. das Umrahmen von "Überschriften" oder Abschnitten z.B.:

        // ***************************
        // Public Methoden
        // ***************************

oder

/* 
 * Das ist ein
 * mehrzeiliger
 * Kommentar
 */

Was mit besonders gefällt und ich hier schon öfter gesehen habe war die Trennung der Methoden mittels:

        //==============================================================================
        private void myScrollBar_ValueChanged(object sender, EventArgs e)
        {
            ZeileFokusieren(myScrollBar.Value);
        }

        //==============================================================================
        private void ZeileFokusieren(int Scrollwert)
        {
            dataGridView1.FirstDisplayedScrollingRowIndex = Scrollwert;
        }

Mittlerweile trenne ich fast alle meine Methoden mit so einem Strich.

Manchmal kommt es aber vor, dass man in einer File mehrere Methoden hat, die man gruppieren kann... aber wie trennt man jetzt solche Gruppen optisch von einander?

Bisher mach ich das so:

        //*****************************************************************************
        // Die Threads:
        // *****************************************************************************

Wann benutzt ihr für EINZEILIGE Kommentare diesen Kommentar

// Kommentar

und wann diesen:

/* Kommentar */

Ich befinde mich zurzeit noch bei der Suche nach dem "besten Style"...
d.h.: Optisch ansprechend, strukturierend, aber auch nicht "overdressed"

Benutzt ihr immer den gleichen Style? Oder kommentiert ihr nach Lust und Laune?

Und noch was: Deklariert ihr alle globalen Variablen immer am anfang der Klasse oder vor den Methodenblöcke die damit arbeiten?

Hallo Cuin,

Ich benutze eigentlich bei meinem Methoden immer die dreifach Variante /// Da ist ja schon quasi gewisser Overheat dabei, aber ich finde es einfach schön und lässt sich so alles gut Beschreiben.

Ansonsten mache ich häufiger mal in Datei am Anfang ne Beschreibung mit Autor etc.

Globale Variablen versuche ich so gut es geht zu umgehen, wenn es mal dazu kommt deklariere ich sie am Anfang der Datei, weil dann muss sie so wichtig sein das sie quasi in allem der Datei gebraucht wird. Z.b. Konstanten.

Viele Grüße,

Kaji

Hallo,

Manchmal kommt es aber vor, dass man in einer File mehrere Methoden hat, die man gruppieren kann... aber wie trennt man jetzt solche Gruppen optisch von einander?

Schau dir mal

#region Irgendwas
#endregion Irgendwas

an.

Ich habe mir hierfür z.B. ein Snippet gemacht (Anhang) auf das du mittels reg zugreifen kannst

Bei mir haben alle Funktionen, Properties und Events diesen Standard-Header, deren leere Struktur man bekommt, wenn man über der Funktion "///" eingibt (ich weiß nicht ob es dafür ein Wort gibt). Egal, ob public oder private.
Lediglich bei privaten Variablen der Klasse lasse ich Kommentare meist weg.
Ansonsten sind bei mir alle Klassen gegliedert über Regions, auf die frisch schon verwiesen hat. Die Meinung dazu ob regions ein gutes oder schlechtes Stilmittel sind gehen zwar sehr weit auseinander (weil einige meinen sie wären nur da um schlechten Code zu verstecken), aber ich für meinen Teil heiße sie für sehr gut wenn sinnvoll verwendet.
Ich teile allerdings nicht auf in private oder public sondern thematisch nach Deklarationen, Event-Handling, Konstruktoren, Properties, Funktionen, Interface-Implementierungen etc., und ggf. darunter nochmal thematische Untergliederungen.
Eine andere Möglichkeit neben den regions (die ich allerdings aufgrund der wachsenden Dateimenge nicht so mag) sind partial classes. Nuja für EventHandling-Funktionen manchmal ganz nett aber sonst sind mir regions lieber weil alles in einer Datei ist, ist aber Geschmackssache.
Weitere optische Gliederungsmöglichkeiten habe ich bisher noch nicht gebraucht, prinzipiell sollte eine Klasse ja genau eine Verantwortlichkeit haben und dann reichen ein Kommentar im Dateiheader, kommentierte Funktionen (und sinnvolle regions) meist aus.

gruß
sth_Weird

Das sind schon mal viele gute tipps dabei^^

habe das mit den regions noch garnicht gewusst, wofür die da sind... benutze sie jetzt auch in meine programm^^ danke für die hinweise....

Bei mir haben alle Funktionen, Properties und Events diesen Standard-Header, deren leere Struktur man bekommt, wenn man über der Funktion "///" eingibt (ich weiß nicht ob es dafür ein Wort gibt).

Die heißen XML-Dokumentationskommentare. Die gibt' bei mir auch für Methoden und Properties (alle!). Solch Trennstriche halte ich total störend - zumal man durch die Dokumentationskommentare ja eine m.E. ausreichende Trennung hat.

habe das mit den regions noch garnicht gewusst, wofür die da sind... benutze sie jetzt auch in meine programm

Ich hasse Regions. Zum Glück gibt's Suchen&Ersetzen mit regulären Ausdrücken. Eine Trennung von Feldern, Properties, Methoden usw. ist unnötig, da man ja erstens sieht, dass worum es sich handelt, und zweitens durch Codingrichtlinien auch klar sein sollte, wo man was findet.
Und wenn man Regions braucht, hat man zu große (Monilith-)Klassen, die zu viel machen. Regions braucht man nicht.

Gruß,
dN!3L

Und wenn man Regions braucht, hat man zu große (Monilith-)Klassen, die zu viel machen. Regions braucht man nicht.

Wenn man selber eine Klasse schreibt und auch z. B. Events zur verfügung stellt so macht eine Region durchaus Sinn, weil Events definiert man in der Regel nur einmal und verändert diese kaum und durch Regionen kann man diese dann ausblenden.

[...]und durch Regionen kann man diese dann ausblenden.

Wenn man Dinge ausblendet/ausblenden kann, sind sie unwichtig. Wenn sie unwichtig sind, kann man sie auch weglassen...

Gefällt dir "Man kann den Code gliedern und die Methoden in Gruppen zusammenfassen" besser? 😛
Und wenn du das mit Regions machen willst, dann schau dir mal das Programm Regionerate an (geht mittlerweile glaub auch ohne Regions und nur mit Kommentaren

Und wenn du das mit Regions machen willst, dann schau dir mal das Programm Regionerate an (geht mittlerweile glaub auch ohne Regions und nur mit Kommentaren

http://www.rauchy.net/regionerate/ 👍

Ich denke nicht dass dieser Thread die richtige Stelle ist um das Pro und Control für regions zu erörtern... [EDIT=herbivore]nach der Anpassung des Titels schon[/EDIT] aaaber...
Ich verstehe nicht warum man immer auf andere spezielle Tools zurückgreifen soll, um Code automatisch übersichtlicher zu machen (oder teilweise genau das zu erreichen, was man mit regions günstiger haben könnte).
Also regions werden bescholten, sie würden schlechten Code verstecken oder zu umfangreiche Klassen vertuschen. Aber wenn im gleichen Zug auf solche Tools verwiesen wird, da frage ich mich, wenn ich die denn brauche, ist denn der Code dann nicht gerade dann schlecht oder zu lang?
Letztendlich sind regions doch nichts weiter als ein Mittel, um Code schön zu gliedern, das, wie alles andere auch, missbraucht werden kann, und das zu verhindern, obligt der Selbstdisziplin des Programmierers.

gruß
sth_Weird

Aber wenn im gleichen Zug auf solche Tools verwiesen wird, da frage ich mich, wenn ich die denn brauche, ist denn der Code dann nicht gerade dann schlecht oder zu lang?

Hat imho nichts mit der Länge des Codes zu tun. Außerdem wollen wir hier niemanden überzeugen oder bekehren, wir wollen lediglich die unterschiedlichen Alternativen aufzeigen. Wie man es macht, sollte jeder selbst entscheiden, und dann im besten Fall konsequent durchziehen. Dabei können einem dann solche Tools wie Regionerate unterstützen.

Wenig aussagekräftige Methoden pack ich der Übersichtlichkeit halber auch immer in regions. Getter und Setter Methoden zBsp.

Solch Trennstriche halte ich total störend - zumal man durch die Dokumentationskommentare ja eine m.E. ausreichende Trennung hat.

Ok, hört sich sinnvoll an.... außer man hat viele Methoden, die man nicht bespreiben muss, weil sie selbstbeschreibend sind (z.b. events, ButtonClick usw.)
Und dann verliert man schnell den Überblick, wenn man zwischen den Methoden hin und her springen muss... ging mir jedenfalls so bisher....
Deshalb habe ich auch die Trennstricke gemacht, damit ich mich besser zurecht finde...

Ich selber habe die XML-Dokumentation noch nicht benötigt. In meiner derzeitigen Firma (mache praktikum) gibt es auch keine C#-Richtlinien, die gibt es nur für C, weil wir fast nur in C programmieren (Embedded Systems)....

das mit den regions hab ich schon kapiert^^ hat vor und nachteile... ich benutze sie um den für die weitere Entwicklung unbenötigten Code wegzublenden...^^

Gibts eventuell einen gewissen Trend zu dem ganzen? Aber bitte nicht einfach weglassen ^^

@dN!3L
Du sprichst dich in dem Thread ja als Gegner von Regions aus. Aber grade wenn man die XMLKommentare fürs IntelliSense benutzt wird das ohne relativ schnell sehr übersichtlich. Was machst du da um das ganze übersichtlicher zu halten?

btw hab ich mal einen Screenshot einer Testklasse mit der ich den Umgang mit XML in C# probiert hatte angehängt. Da ist mal alles zugeklappt bis auf eine Region. Versuchs halt nach logischen zusammengehörigekeiten zu kapseln.