Laden...

Kommentare im Code - Ja oder Nein - Wie ist eure Meinung?

Erstellt von mankingwwe vor 6 Jahren Letzter Beitrag vor 6 Jahren 21.009 Views
M
mankingwwe Themenstarter:in
39 Beiträge seit 2018
vor 6 Jahren
Kommentare im Code - Ja oder Nein - Wie ist eure Meinung?

Hey
ich bin seit August in der Ausbildung Fachinformatiker Anwendungsentwicklung.
Ich bin nun seit 1 Monat in meiner 2. Abteilung und es gibt einen Glaubenskrieg.

In meiner ersten Abteilung wurde mir gesagt Kommentare gehören nicht in den Code. Wenn man Kommentare braucht hat man nicht genug über die Benennung seiner Methoden etc nachgedacht, der Code muss sich selbst wie eine Dokumentation lesen.

Nun in der zweiten Abteilung wird mir gesagt ich soll bloß Kommentare schreiben sonst gibt es ärger. Kommentare seien wichtig und würden Entwicklern nach mir helfen.

Der Kommentar der ersten Abteilung dazu, als ich es erzählt habe, war nur das anscheinend da ein paar Kollegen noch nicht im nächsten Jahrhundert angekommen wären.

Würde gerne wissen was ihr denkt 😃
Dokumentation ja oder nein?

2.207 Beiträge seit 2011
vor 6 Jahren

Hallo mankingwwe,

In meiner ersten Abteilung wurde mir gesagt Kommentare gehören nicht in den Code. Wenn man Kommentare braucht hat man nicht genug über die Benennung seiner Methoden etc nachgedacht, der Code muss sich selbst wie eine Dokumentation lesen.

Ich bin einer, der zu 99% dieser Abteilung angehört. Code sowie das Testing sollte eine Dokumentation des Codes geben. Ganz ausschliessen kann man es nie. Aber ich habe nur ganz ganz selten wirklich sinnvolle Kommentare gesehen. Mich stören sie eher beim Lesen und sie werden sehr oft nicht mit gewartet - gehen einfach vergessen.

Musste auch schonmal Properties kommentieren a la


// gets and sets the name
public string Name { get; set; }

was nun wirklich sinnfrei war.

Falls du aber eine Lib auf NuGet o.ä. zur Verfügung stellst wäre es schon sinnvoll öffentliche Methoden zu beschreiben. Was sie tun, wie der Rückgabetyp ist etc. bei sowas finde ich es schon sinnvoll. https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/xml-documentation-comments . Aber auch da finde ich es nur für "öffentliche" (in- oder extern) Softwarepakete wirklich angebracht.

Gruss

Coffeebean

T
2.219 Beiträge seit 2008
vor 6 Jahren

Ich glaube die Leute in der ersten Abteilung haben nie wirklich programmiert 😕
Kommentare sind das A und O von gutem Code.
Um so größer und komplexer ein Projekt wird, um so wichtiger ist die Dokumentation sowie gute Kommentare.

Kommentare im Code haben nur am Rande mit Methodennamen zu tun.
Diese sollten sowohl bei Methoden(Summary) eine Erklärung der Methode sein und auch Informationen liefern was dort für Parameter übergeben werden.

In den Methoden oder an anderen Stellen soll Code auch informieren wozu bestimmte Abläufe umgesetzt wurden.
Wenn jemand Code vorlegt, der unkommentiert ist, kann er ihn behalten.
Niemand will sich die Mühe machen durch Tausende Zeilen Code zu lesen um zu verstehen was passiert oder warum bestimmte Funktionen umgesetzt wurden.

Jemand der Ernsthaft Geld mit Software Entwicklung verdient, nutzt Kommentare so oft wie möglich aber auch nur so oft wie nötig.
Keine, zu wenige oder zu viele Kommentare schaden dem Code einfach.
Hier muss man eine angemessene Menge an Kommentaren einfach voraussetzen können.

T-Virus

Developer, Developer, Developer, Developer....

99 little bugs in the code, 99 little bugs. Take one down, patch it around, 117 little bugs in the code.

2.207 Beiträge seit 2011
vor 6 Jahren

mankingwwe du siehst, auch hier gehen die Meinungen auseinander 😃

16.806 Beiträge seit 2008
vor 6 Jahren

Puh.. das ist das gefühlt 19. millionste Thema dazu.
Bisher war die Devise und die Best Practise in Unternehmen: so wenig wie möglich, aber so viel wie nötig

T
2.219 Beiträge seit 2008
vor 6 Jahren

@Abt
Und es wir noch mindestens 19 Mio. mehr davon geben. 😃
Die Geister scheiden sich hier eben sehr stark.

T-Virus

Developer, Developer, Developer, Developer....

99 little bugs in the code, 99 little bugs. Take one down, patch it around, 117 little bugs in the code.

16.806 Beiträge seit 2008
vor 6 Jahren

Und was soll die Antwort davon sein?
Es wird keine geben.

T
2.219 Beiträge seit 2008
vor 6 Jahren

Die Antwort muss jeder für sich selbst aus den Argumenten bilden.
Ich habe meine Meinung und nutze eben Kommentar so gut es geht und sinnvoll ist.
Wer es nicht nutzt, kann es eben lassen.

Hier muss der TE sich eben entscheiden, was ihm weiter hilft.
Eine Antwort für alle wird es bei solche einer Fragt nicht geben.
Darum geht es hier auch nicht.

Hier geht es eher darum die Argumente dafür oder dagegen vorzulegen.
Ich halte dies für eine Möglichkeit auch mal eine Sichtweise auf die andere Seite zu bekommen und vielleicht auch gute Argumente gegen Kommentare im Code.

T-Virus

Developer, Developer, Developer, Developer....

99 little bugs in the code, 99 little bugs. Take one down, patch it around, 117 little bugs in the code.

D
985 Beiträge seit 2014
vor 6 Jahren

Man muss die Kommentare in zwei Bereiche teilen, denn diese adressieren unterschiedliche Rollen.

Die Kommentare vor der Methode/Eigenschaft (XML-Dokumentation) sind zum großen Teil für diejenigen Entwickler gedacht, die diese Klasse verwenden wollen/sollen.

Da sollte also vermerkt sein, was man von dieser Methode zu erwarten hat und was für Exceptions kommen könnten. Wer sich nicht sicher dabei ist, der schaut sich einfach mal die MSDN Dokumentation an.

Kommentare im Code sind primär für die Entwickler gedacht, die diese Methode implementieren oder überarbeiten. Hier sollte das Ziel sein, so gut wie ohne Kommentare auszukommen. Sprechende Namen (Variablen, Methode, Eigenschaften) helfen dabei ungemein.

P
1.090 Beiträge seit 2011
vor 6 Jahren

Bisher war die Devise und die Best Practise in Unternehmen: so wenig wie möglich, aber so viel wie nötig

Ich schließe mich da Abts Meinung an. (Und auch Sir Rufos aussage).

Was man sicher Festhalten kann, ist alles zu Kommentieren ist sicher falsch. Und nicht zu Kommentieren auch.

Ich denke man sollte hier einfach Überdenken, wo zu Kommentare da sind.

Und meines Erachtens sind sie dafür da anderen Entwicklern dabei zu Helfen produktive Arbeiten zu können.

Es gibt da einfach Kommentare, die sinnlos sind. Wie:

//Erzeuge Kunde
var kunde = new Kunde();  

Es gibt aber auch immer Kommentare die sinnvoll sind. Grade wenn es um Workaraunds geht, weil es in der Speziellen Situation noch Fehler im „Framework“ geht.


//Workaround
//EF Core unterstützt noch kein Server seitiges Group By
// Link: https://....
//Darum ...

Grundlegend ist es meist sinnvoller statt einen Kommentar, der sich auf Mehrere Zeilen Quelltext Bezieht. Diese in eine eigen Methode auszulagern und der Methode einen sinnvollen Namen zu geben. Wenn ich dann in der Methode was ändere und den Namen anpassen muss, ändert er sich an allen Stellen wo die Methode aufgerufen wird.

Wenn deine Kollegen verstehen was du machst, ohne das du Kommentare schreiben musst. Ist das sehr gut.

Wir machen es bei uns so das Codereviews statt finden. Und das dann auch über Kommentare gesprochen wird.

Wenn bei euch die Beiden Abteilungen so unterschiedliche Auffassungen von Kommentaren haben. Liegt es eigentlich nahe (wenn sie die gleiche Programmiersprache verwenden), mal gegenseitig Codereviews machen.

Hier ist dann aber wichtig es nicht unter den Motto zu machen, ihr seid aber Sch... . Sondern man Arbeitet zusammen, damit alle besser werden. Das ist aber sicher ein anderes Thema.

Sollte man mal gelesen haben:

Clean Code Developer
Entwurfsmuster
Anti-Pattern

M
mankingwwe Themenstarter:in
39 Beiträge seit 2018
vor 6 Jahren

Danke für die Antworten 😃 Interessantes Thema, aber habe nun Begriffen, dass es anscheinend keine richtige Antwort gibt.

C
2.121 Beiträge seit 2010
vor 6 Jahren

Wer beschreibt dass eine Variable mit dem Namen "Kunde" ein Kundenobjekt enthält, dem wurde Unsinn verordnet. Natürlich ist das Quatsch.

Jetzt was zum überlegen. Wer die Intellisense Beschreibungen der Frameworkmethoden liest, kann schon nicht mehr ernsthaft behaupten man könnte Methoden so benennen dass man keine Beschreibung mehr braucht.
Gerade spezielles Verhalten bei Fehlern oder bestimmten Sonderfällen sieht man einem Namen nicht an. Außer man nennt seine Methode ParseNumberAndThrowExepctionIfLowerThanZeroBecauseThisClassNeedsPositiveValues.

Als Azubi wird einem nichts übrig bleiben als Kommentare einfach wegzulassen, wenn die das so wollen. Falls mal jemand fragt was der Code tut sollte man den Mut haben zu sagen, weiß ich nicht - ich durfte es ja nicht dazu schreiben. Dann wäre für mich der Fall erledigt.

301 Beiträge seit 2009
vor 6 Jahren

Kommt mMn. immer auf diejenigen an die es später lesen sollen. Ich dokumentiere keinen Code von dem ich weiß, dass nur ich ihn jemals wieder sehen werde. Beim umgekehrten Fall gehe ich davon aus, dass es der unerfahrendste Entwickler im Umfeld verstehen soll. Da sind Kommentare nicht immer vermeidbar. Informationen in Kommentaren müssen halt auf den Punkt gebracht werden.

Passende Bezeichnungen für Identifier sind extrem wichtig aber auch nicht immer so möglich, dass komplexere Zusammenhänge verständlich sind.

API's sollten meiner Meinung nach gut dokumentiert sein. Das ist Code den andere nutzen und verstehen müssen. Sowas dokumentiere ich gut und gerne. Alles weitere ist Geldverschwendung.

Wie willst du gewährleisten das auch die dümmsten Entwickler genau verstehen was du dir überlegt hast? -> Es geht nicht.

16.806 Beiträge seit 2008
vor 6 Jahren

Kommt mMn. immer auf diejenigen an die es später lesen sollen. Ich dokumentiere keinen Code von dem ich weiß, dass nur ich ihn jemals wieder sehen werde. Truck Number

Code muss immer so entwickelt werden, dass jemand anderes damit was anfangen kann.
Das fängt vor allem beim Naming des Codes an ( [Artikel] C#: Richtlinien für die Namensvergabe ). Der Mehrwert ist hier riesig.

Bei Kommentaren kommt es hingegen drauf an, ob dadurch der Wert steigt.
Klarer Code ist definitiv wichtiger als alles zu kommentieren. Oft nennt man sie nicht umsonst die "grünen Lügen".

301 Beiträge seit 2009
vor 6 Jahren

Damit meinte ich private eigene Projekte. In der Firma gehe ich davon aus das ich nie der einzige bin der es liest da bei uns jede Zeile Code durch Codereviews geht.

War missverständlich ausgedrückt 😃

2.207 Beiträge seit 2011
vor 6 Jahren

Oft nennt man sie nicht umsonst die "grünen Lügen". 👍

P
1.090 Beiträge seit 2011
vor 6 Jahren

Gerade spezielles Verhalten bei Fehlern oder bestimmten Sonderfällen sieht man einem Namen nicht an. Außer man nennt seine Methode ParseNumberAndThrowExepctionIfLowerThanZeroBecauseThisClassNeedsPositiveValues.

Du beschreibst an dem Punkt was die Methode alles mach und nicht wo zu sie da ist, also ihre Funktion.

Die Signatur deiner Methode könnte so aussehen.

int PrasePositiveNumber(String value)

Ich denke die Meisten Entwickler können dann direkt am Quellcode sehen, was die Methode macht, da brauche ich keinen Kommentar direkt vor dem Methoden Aufruf. Ein Summarie für die Methode kann, sicher nicht schaden.
Aber ein guter Methoden Name ist da deutlich besser. Dann brauche ich mir erst gar nicht die Summaries anzuschauen.

Die Frage betritt im Übergen „Kommentare im Code - Ja oder Nein - Wie ist eure Meinung?“
Da Zähle ich Summeries nicht direkt dazu.

Für mich geht es da eher im Punkte, wo direkt in der Methode steht was die Nächten Zeilen machen.

Hier male ein Beispiel:
Refactoring:Extract Methode

Sollte man mal gelesen haben:

Clean Code Developer
Entwurfsmuster
Anti-Pattern

C
2.121 Beiträge seit 2010
vor 6 Jahren

@Palin
Da haste Recht, es ist immer gut zu wissen wie eine Frage im Detail gemeint ist. Ich hätte Summaries auch als Kommentar gesehen. Das lassen manche noch lieber weg als Kommentare zwischen Codezeilen.

Jeden Aufruf kommentieren ist auch nicht Sinn der Sache. Aber Details erklären, vielleicht eine Berechnung oder Auswertung erklären, sowas darf man meiner Meinung gerne als Kommentar hinterlassen.

Die Wahrheit liegt sicher weder bei "ja, immer alles kommentieren" noch bei "nein, nie etwas kommentieren", sondern dazwischen. Es kommt eben darauf an. Wenn man auf festen Vorgaben beharrt, möglichst noch von jemandem der sich selbst nicht dran halten muss, hat man immer verloren.

P
1.090 Beiträge seit 2011
vor 6 Jahren

Grundlegend denke ich sind wir uns da einig. Auch wenn ich mir die anderen Kommentare hier im Thread anschaue.

Ohne Kommentare kommen wir nicht aus. Es ist aber auch nicht sinnvoll alles zu Kommentieren.

Ich denke was ein Punkt ist, der oft in der Software Entwicklung übersehen wird. Ist das es an vielen Punkten nicht einfach richtig oder falsch gibt. (Liegt vielleicht daran das wir zu viel mit Einsen und Nullen zu tun haben). Sondern man auch mit Menschen zusammen Arbeitet.
Und da geht es dann auch darum Kompromisse zu finden, so das man Produktive zusammen Arbeiten kann.

Sollte man mal gelesen haben:

Clean Code Developer
Entwurfsmuster
Anti-Pattern

M
1 Beiträge seit 2008
vor 6 Jahren

Also insbesondere der Kommentar, "das anscheinend da ein paar Kollegen noch nicht im nächsten Jahrhundert angekommen wären", zeugt von unglaublicher Arroganz der Kollegen im nicht-kommentierenden Team.
Ok, diese Arroganz kann man natürlich auch umdrehen: Die Nicht-Kommentierer sind offenbar JavaScript-Hipster, deren unnötige Projekte nach einem Jahr ohnehin keiner mehr lesen muss.

Man sollte insbesondere bei ernsthaften Anwendungen IMMER davon ausgehen, dass die Anwendung so lange lebt, dass irgendwann ein Team daran entwickelt, das bei der ursprünglichen Entwicklung nicht dabei war. Und so sinnvoll, wie gute Namen für Methoden und Variablen sind, so dankbar werden diese Entwickler dir sein, wenn du auch kommentierst, WARUM du etwas auf bestimmte Art und Weise implementiert hast.
Sei es:

  • Weil es so schneller läuft/weniger Speicher verbraucht whatever
  • Weil die verwendete Komponente einen Bug hat und du ihn somit umschiffst
  • Weil der Workflow nunmal genau so gefordert war und du leider überstimmt wurdest
  • Weil irgendwelche Daten in einem Format geliefert werden, was du nicht beeinflussen kannst
  • uswusf

Ich erlebe es öfters (also sagen wir mal alle paar Wochen), dass ich zu Kollegen sage "Kommentier unbedingt, WARUM das so implementiert ist. Sonst versteht das in einem Jahr kein Mensch mehr".

Wer meint, dass er keine Kommentare braucht, entwickelt wahrscheinlich die x-tausendste Aufgabenliste oder hat noch nicht in seinem Leben an wirklich großen Softwareprojekten gearbeitet. Wer meint, dass sich alles aus guten Namen und Tests automatisch erschließt, ist naiv und unerfahren. Jeder der so etwas dummes von sich gibt, sollte gezwungen werden, an unkommentierten MFC-Projekten aus den 90ern zu arbeiten.
Und wer meint, sein eigener Code ist so toll lesbar, dass er auch in 20 Jahren noch durch einfaches Draufschauen verstanden werden kann, hat zuerst einmal ein großes Problem mit Selbstreflektion.

Kurz gesagt: Schreib Kommentare im Code, wo du erklärst, WARUM etwas auf bestimmte Art und Weise implementiert wurde. Aber lass all die unsinnigen Kommentare weg, wo nur das wiederholt wird, was im Code ohnehin schon steht (Beispiele gab es ja schon zur Genüge).

463 Beiträge seit 2009
vor 6 Jahren

Kurz gesagt: Schreib Kommentare im Code, wo du erklärst, WARUM etwas auf bestimmte Art und Weise implementiert wurde. Aber lass all die unsinnigen Kommentare weg, wo nur das wiederholt wird, was im Code ohnehin schon steht (Beispiele gab es ja schon zur Genüge).

Ich denke, damit hast du es auf den Punkt gebracht - wer so dokumntiert, der dokumentiert richtig.