Wie gehe ich mit einem Teammitglied um, das keine Kommentare im Code machen möchte?

Eines meiner Teammitglieder vermeidet konsequent Kommentare in seinem Code.

Sein Code ist nicht selbstdokumentierend, und andere Programmierer haben Schwierigkeiten, seinen Code zu verstehen.

Ich habe ihn mehrmals gebeten, seinen Code zu kommentieren, aber er gibt nur Ausreden oder behauptet, dass er es später tun wird. Sein Anliegen ist, dass das Hinzufügen von Kommentaren zu viel Zeit in Anspruch nimmt und die Projekte verzögert.

Welches Argument kann ich ihm vorlegen, um ihn davon zu überzeugen, seinen Code ordnungsgemäß zu dokumentieren?

In diesem Sinne bin ich falsch, mich auf die Codekommentare zu konzentrieren, oder deutet dies auf ein größeres Problem hin, das angegangen werden sollte?

Kommentare allein sorgen nicht für besseren Code, und wenn Sie nur auf "mehr Kommentare" klicken, erhalten Sie wahrscheinlich nur /* increment i by 1 */Stilkommentare.

Fragen Sie sich also, warum Sie diese Kommentare wünschen. "Es ist die beste Vorgehensweise" gilt nur dann als Argument, wenn Sie verstehen, warum.

Der auffälligste Grund für die Verwendung von Kommentaren ist, dass der Code einfacher zu verstehen ist. Wenn sich die Leute über das Fehlen von Kommentaren beschweren, sind sie entweder ahnungslose Papageien oder es fällt ihnen schwer, den Code zu verstehen, mit dem sie arbeiten.

Beschweren Sie sich also nicht über fehlende Kommentare: Beschweren Sie sich über unlesbaren Code. Oder noch besser, beschweren Sie sich nicht, sondern stellen Sie immer wieder Fragen zum Code. Wenn Sie etwas nicht verstehen, fragen Sie die Person, die es geschrieben hat. Das solltest du sowieso tun; Bei unlesbarem Code stellen Sie einfach weitere Fragen. Wenn Sie später noch einmal auf einen Teil des Codes zurückkommen und sich nicht sicher sind, was er bewirkt, stellen Sie die gleiche Frage erneut.

Wenn Kommentare Abhilfe schaffen und Ihr Kollege ein funktionierendes Gehirn hat, wird er / sie irgendwann feststellen, dass das Kommentieren des Codes viel einfacher ist, als wenn Sie ständig dumme Fragen stellen. Und wenn Sie keine Fragen haben, ist dieser Code möglicherweise bereits perfekt lesbar, und Sie sind schuld - schließlich braucht nicht jeder Code Kommentare.

Vermeiden Sie es, sich im Bereich der menschlichen Fähigkeiten herablassend oder beschuldigend zu verhalten. Seien Sie ernst und ehrlich in Bezug auf Ihre Fragen.

Ich habe viele Entwickler getroffen, die Schwierigkeiten hatten, selbstdokumentierenden Code oder hilfreiche Kommentare zu schreiben. Diesen Menschen fehlt oft genug Selbstdisziplin oder Erfahrung, um es richtig zu machen.

Was nie funktioniert, ist "ihnen zu sagen, dass sie mehr Kommentare hinzufügen sollen". Dies erhöht weder ihre Selbstdisziplin noch ihre Erfahrung. IMHO ist das Einzige, was funktionieren könnte, häufige Code-Reviews und Refactoring-Sitzungen durchzuführen. Wenn ein Entwickler eine Aufgabe abgeschlossen hat, lassen Sie ihn Teile des Codes erklären, die Sie nicht verstehen. Überarbeiten oder dokumentieren Sie den Code sofort so, dass Sie beide 6 Monate später verstehen.

Tun Sie dies über einen Zeitraum von einigen Monaten, mindestens zweimal pro Woche. Wenn Sie Glück haben, lernen die anderen Entwickler durch diese Sitzungen, so dass Sie die Überprüfungshäufigkeit reduzieren können.

Ich bin überrascht, dass noch niemand Code-Reviews erwähnt hat. Machen Sie Code-Reviews! Wenn er schlecht eingecheckt hat, sag nicht einfach "Kommentar hinzufügen". Stellen Sie ständig Fragen und lassen Sie sich von ihm erklären, was sein Code tut und warum. Mache Notizen. Geben Sie ihm am Ende der Codeüberprüfung eine Kopie der Notizen und bitten Sie ihn, Ihre Fragen ziemlich offensichtlich zu machen. Entweder durch mehr Kommentare oder einfach durch Überarbeitung seines Codes, um die Qualität zu verbessern (vorzugsweise letzterer, wenn möglich).

Dies hängt vom Code ab, den Ihr Teamworker erstellt. Wenn Sie das Clean Code- Buch von Onkel Bob lesen, werden Sie feststellen, dass er es tatsächlich vorzieht, dem Code keine Kommentare hinzuzufügen. Wenn der Code selbst so lesbar ist, wie er sein sollte, sind kaum Kommentare erforderlich.

Wenn dies nicht der Fall ist oder Sie aufgrund einer nicht verhandelbaren Richtlinie Kommentare benötigen, wird die Hauptfrage lauten, ob nur Sie Kommentare von ihm / ihr schreiben lassen möchten oder ob es sich um das gesamte Team oder das Team / Projekt handelt Führer. Wenn es nur Sie sind, sollten Sie mit Ihren anderen Kollegen sprechen, um herauszufinden, warum es überhaupt keine so große Sache sein kann.

Wenn dem Projektleiter die Kommentare fehlen, können Sie diese auch zur Vollständigkeit anfordern, dh wenn der eingereichte Code keine Kommentare enthält, ist die Arbeit noch nicht abgeschlossen. Er darf keine anderen Arbeiten mehr ausführen, bis seine aktuelle Arbeit beendet ist und dafür Kommentare erforderlich sind. Bedenken Sie jedoch, dass diese Art des Erzwingens höchstwahrscheinlich zu schrecklichen Kommentaren führen wird (erwarten Sie eine Menge beschissener Wiederholungen von Code-Kommentaren).

Meiner bescheidenen Meinung nach ist es nur möglich, die tatsächlichen Gewinne zu besprechen, die Sie und alle anderen aus Kommentaren ziehen. Wenn er / sie es nicht durch bloße Diskussion versteht, gibt es auch immer den schwierigen Weg: Anstatt sie neuen Code schreiben zu lassen, müssen sie mit vorhandenem Code arbeiten. Wenn möglich, sollten Sie zwei verschiedene Arbeitsbereiche finden - einen mit nützlichen Kommentaren und einen ohne Kommentare. Das Lesen des nicht lesbaren, nicht kommentierten Codes einer anderen Person ist ein Augenöffner für Ihre eigene Arbeit.

Wir waren alle einmal dort und waren wütend auf den ursprünglichen Autor einer Quelle, die so schlampig gearbeitet hat. Es ist die zusätzliche Überlegung, dass jeder von uns auch so ein Autor ist, dass Sie erkennen, dass Sie sich um die Lesbarkeit kümmern sollten. Vergessen Sie daher nicht, die Ergebnisse anschließend mit Ihrem Kollegen zu besprechen, um diese Überlegung zu fördern.

Wenn Sie einen Mitarbeiter haben, der Anweisungen nicht befolgen kann, tadeln Sie ihn und stellen Sie sicher, dass dies nicht zu einem beruflichen Aufstieg beiträgt. Die Konsistenz des Codierungsstils ist für ein Team von entscheidender Bedeutung. Wenn alle anderen Kommentare schreiben und dies nicht der Fall ist, wird der Codierungsstil beeinträchtigt.

Das heißt, Sie können ihm wahrscheinlich helfen. Wenn jemand dagegen protestiert, dass das Kommentieren zu lange dauert, gibt es meiner Erfahrung nach eine psychologische Barriere wie ...

1. Er ist sich seiner Code / Design-Entscheidungen bewusst und möchte sie nicht in Prosa auslegen. (Code-Überprüfungen können hilfreich sein, um das Selbstvertrauen einer Person zu stärken und sie niederzureißen.)
2. Er arbeitet sehr linear und denkt nicht viel nach. Das Kommentieren ist schmerzhaft, weil es ihn zwingt, den unmittelbaren Code, den er gerade schreiben wollte, aus seinem Arbeitsspeicher zu entfernen, um seine Absicht auf eine andere Art und Weise zu verfassen. (Wenn dies zutrifft, wird das Kommentieren für seine Codequalität sehr wichtig.)
3. Historisch gesehen verstehen die Leute seine Kommentare nicht.

Für einen Programmierer ist es wichtig zu erkennen, dass Kommentare wie Tests sind: Sie sind nicht nur für die zukünftige Verwendung bestimmt - sie sind für den Programmierer selbst bestimmt. Sie zwingen ihn, anders über seine Herangehensweise zu denken.

Nichts davon ist ein Ersatz für CI, Tests oder Codeüberprüfungen. Es ist nur einer von vielen kritischen Teilen der Codierung, die selbst keinen Code schreiben.

Holen Sie sich Code-Überprüfungssoftware und verwenden Sie sie gut.

Wir benutzen Kiln und wir lieben es. Wir haben die Richtlinie, dass jeder Änderungssatz überprüft werden muss (obwohl wir Entwicklern erlauben, Überprüfungen von Tags und Zusammenführungen ohne Konflikte selbst durchzuführen / zu genehmigen (obwohl die meisten von uns rebaseif verwenden); auf diese Weise können wir schnell Änderungssätze ohne Überprüfungen erkennen).

Code, der nicht klar ist, ist ein Grund dafür, dass eine Codeüberprüfung abgelehnt wird. Es spielt keine Rolle, ob es sich bei der Korrektur um Kommentare oder klareren Code handelt, der Prüfer muss sie jedoch verstehen können. Einige Entwickler bevorzugen den Code neu zu schreiben, aber andere (ich eingeschlossen) findet es oft leichte Absicht in den Kommentaren zum Ausdruck bringt (Code kann leicht zeigen , was es tut, aber es ist schwieriger zu zeigen , was es sollte tun).

Wenn es jemals Fragen zur Klarheit des Codes gibt, gewinnt der Prüfer immer. Natürlich versteht der Autor es, weil sie es geschrieben haben. Es muss einer anderen Person klar sein.

Durch die Verwendung von Software wie Kiln wird kein Änderungssatz übersehen. Jeder in meinem Entwicklerteam zieht es so vor. Die Codeüberprüfungssoftware hat einen enormen Einfluss auf die Codequalität und die Anwendungsqualität :-)

Es ist leicht für Entwickler, sich mit abgelehnten Bewertungen zu wehren, wenn sie zum ersten Mal Software einführen, aber meiner Erfahrung nach dauert es nicht lange, bis sie erkennen, dass die Dinge auf diese Weise besser sind und es annehmen :-)

Bearbeiten: Auch erwähnenswert, wir versuchen, nicht zu haben, dass Entwickler kryptischen Code verbal oder in Kommentaren in der Rezension erklären. Wenn etwas nicht klar ist, können Sie es am besten im Code erklären (in Kommentaren oder durch Refactoring). Fügen Sie dann die neuen Änderungssätze derselben Überprüfung hinzu.

Interessanterweise wird die Lesbarkeit in Bezug auf die natürliche Sprache an der Geschwindigkeit des Lesens und Verstehens gemessen. Ich denke, eine einfache Regel kann in der Tat übernommen werden. Wenn ein bestimmter Codekommentar diese Eigenschaft nicht verbessert, kann er vermieden werden .

Warum Kommentare?

Obwohl der Codekommentar eine Form der eingebetteten Dokumentation ist, gibt es in High-End-Programmiersprachen mehrere Möglichkeiten, um überflüssige "überdokumentierte" Programmierung (von sinnvollem Code) durch Verwendung von Elementen der Sprache selbst zu vermeiden. Es ist auch eine schlechte Idee, Code in Listen aus dem Programmierlehrbuch umzuwandeln, in denen einzelne Aussagen buchstäblich auf fast tautologische Weise erklärt werden (beachten Sie das Beispiel "/ * Inkrement i um 1 * /" in bereits bereitgestellten Antworten), um solche Kommentare relevant zu machen Nur für Programmierer, die mit der Sprache nicht vertraut sind.

Nichtsdestotrotz ist es die Absicht zu versuchen, den "unterdokumentierten" (aber bedeutungslosen) Code zu kommentieren, der wirklich "die Quelle allen Übels" ist. Die bloße Existenz von "unterdokumentiertem" Code ist ein schlechtes Signal - entweder ist es ein unstrukturiertes Durcheinander oder ein verrückter Hack mystischer, verlorener Absicht. Offensichtlich ist der Wert eines solchen Codes zumindest fraglich. Leider gibt es immer wieder Beispiele, bei denen es in der Tat besser ist, einen Kommentar in einen Abschnitt aus (visuell gruppierten) formatierten Codezeilen einzufügen, als ihn in eine neue Subroutine zu packen (beachten Sie die "dumme Konsistenz", die "der Hobgoblin der kleinen Köpfe" ist). .

Codelesbarkeit! = Codekommentare

Für lesbaren Code sind keine Anmerkungen durch Kommentare erforderlich. An jeder bestimmten Stelle im Code befindet sich immer ein Kontext einer Aufgabe, die dieser bestimmte Code erfüllen soll. Wenn der Zweck fehlt und / oder der Code etwas Rätselhaftes tut = um jeden Preis vermeiden. Lassen Sie nicht zu, dass seltsame Hacks Ihren Code füllen - dies ist eine direkte Folge der Kombination fehlerhafter Technologien mit Zeit- und Interessensmangel, um die Grundlagen zu verstehen. Vermeiden Sie mystischen Code in Ihrem Projekt!

Auf der anderen Seite kann Readable program = code + documentation mehrere legitime Abschnitte von Kommentaren enthalten, z. B. um die Erstellung von "Kommentare zur API" -Dokumentation zu erleichtern.

Befolgen Sie die Codestilstandards

Komischerweise geht es bei der Frage nicht darum, warum man Code kommentiert, sondern darum, wie man Code in einem stark synchronisierten Stil erzeugt (den jeder andere lesen / verstehen kann). Befolgen Sie in Ihrem Unternehmen Standards für den Codestil? Das Hauptziel besteht darin, das Schreiben von Code zu vermeiden, der überarbeitet werden muss, zu "persönlich" und "subjektiv" mehrdeutig ist. Wenn man also die Notwendigkeit sieht, einen Code-Stil zu verwenden, gibt es eine ganze Reihe von Werkzeugen, mit denen man ihn richtig implementieren kann - angefangen bei der Aufklärung der Mitarbeiter bis hin zur Automatisierung der Qualitätskontrolle des Codes (zahlreiche Einschränkungen usw.) und (Überarbeitung) Kontrollintegrierte) Code-Überprüfungssysteme.

Werden Sie ein Evangelist für Codelesbarkeit

Wenn Sie damit einverstanden sind, dass Code öfter gelesen wird als geschrieben. Wenn es für Sie wichtig ist, Ideen klar auszudrücken und klar zu denken, egal in welcher Sprache (Mathematik, Maschinencode oder Alt-Englisch). Wenn es Ihre Mission ist, langweilige und hässliche Arten des alternativen Denkens zu beseitigen. (Entschuldigung) , der letzte stammt aus einem anderen "Manifest"). Fragen stellen, Diskussionen anstoßen, nachdenkliche Bücher über Codereinigung verbreiten (wahrscheinlich nicht nur etwas, das Becks Entwurfsmustern ähnelt, sondern eher wie bereits von RC Martin erwähnt ), die sich mit Zweideutigkeiten befassen in der Programmierung. Weiter geht eine Stichprobe von Schlüsselideen (zitiert aus O'Reilly Buch über Lesbarkeit)

• Vereinfachen Sie das Benennen, Kommentieren und Formatieren mit Tipps, die für jede Codezeile gelten
• Verfeinern Sie die Schleifen, die Logik und die Variablen Ihres Programms, um Komplexität und Verwirrung zu verringern
• Angriffsprobleme auf Funktionsebene, z. B. das Reorganisieren von Codeblöcken, um jeweils eine Aufgabe auszuführen
• Schreiben Sie effektiven Testcode, der gründlich und präzise sowie lesbar ist

Wenn man das "Auskommentieren" ausschneidet, bleibt einem noch viel übrig (ich denke, das Schreiben von Code, der keine Kommentare benötigt, ist eine großartige Übung!). Die Benennung semantisch bedeutungsvoller Bezeichner ist ein guter Anfang. Als Nächstes strukturieren Sie Ihren Code, indem Sie logisch verbundene Operationen in Funktionen und Klassen gruppieren. Und so weiter. Ein besserer Programmierer ist ein besserer Schreiber (natürlich unter der Voraussetzung, dass andere technische Fähigkeiten vorhanden sind).

Bin ich falsch, mich auf die Code-Kommentare zu konzentrieren, oder deutet dies auf ein größeres Problem hin, das angegangen werden sollte?

Etwas. Großartiger Code benötigt keine Kommentare. Wie Sie sagten, ist sein Code jedoch nicht selbstdokumentierend. Ich würde mich also nicht auf die Kommentare konzentrieren. Sie sollten sich darauf konzentrieren, die Fähigkeiten und das handwerkliche Können Ihrer Entwickler zu verbessern.

Also, wie geht das? Doc Browns Vorschläge zu Reviews / Refactoring-Sitzungen sind eine gute Idee. Ich finde die Paarprogrammierung noch effektiver, aber die Implementierung kann auch erheblich schwieriger sein.

Zuallererst würde ich vorschlagen, dass Sie Ihre Herangehensweise an die Kommentare erneut ansprechen.

Wenn es sich um Dokumentationskommentare auf API-Ebene handelt (die später der Öffentlichkeit zugänglich gemacht werden), ist dieser Entwickler einfach nicht in der Lage, seine Arbeit zu erledigen. Aber für alle anderen Kommentare sei vorsichtig.

In den meisten Fällen, in denen ich ihnen begegne, sind Kommentare böse. Ich würde empfehlen, das Kapitel mit den Codekommentaren von "Clean Code" von Robert Martin zu lesen , um zu verstehen, warum.

Kommentare schaden Ihrem Code auf verschiedene Weise:

1) Sie sind schwer zu pflegen. Beim Refactoring müssen Sie zusätzliche Arbeit leisten. Wenn Sie die im Kommentar beschriebene Logik ändern, müssen Sie auch den Kommentar bearbeiten.

2) Sie lügen oft. Sie können Kommentaren nicht vertrauen und müssen stattdessen den Code lesen. Was die Frage aufwirft: Warum brauchen Sie die Kommentare überhaupt?

// this method returns the sum of 'a' and 'b'
public int GetHash(int a, int b)
{
    //the calculation of the hash
    int result = a*b;
}

(Der Hash ist nicht die Summe, sondern das Produkt.)

3) Kommentare machen den Code unübersichtlich und fügen nur sehr selten einen Wert hinzu.

Meine Lösung: Anstatt weitere Kommentare hinzuzufügen, sollten Sie versuchen, diese überhaupt loszuwerden!

Wenn ein Teammitglied Probleme hat, den Code eines anderen Teammitglieds zu verstehen (aus irgendeinem Grund); Dann sollte das Teammitglied in der Lage sein, herauszufinden, wer den Originalcode geschrieben hat (jedes vernünftige Revisionskontrollsystem), und sollte aufgefordert werden, den Autor des Codes zu bitten, ihn direkt zu erklären (z. B. zu seinem Schreibtisch zu gehen, sich hinzusetzen und darüber zu diskutieren).

Wenn in diesem Fall das Fehlen von Kommentaren ein Problem darstellt, verbringt die Person, die ihren Code nicht ausreichend kommentiert, einen großen Teil ihrer Zeit damit, zu erklären, was sie getan hat. und (wenn sie schlau sind) werden Kommentare hinzugefügt, um Zeit für all diese Erklärungen zu sparen.

Beachten Sie, dass es aus anderen Gründen sinnvoll ist, Teammitglieder zu ermutigen, sich gegenseitig um Erklärungen zu bitten. Beispielsweise ist ein Teammitglied möglicherweise weniger erfahren und kann von den erfahreneren Teammitgliedern etwas lernen.

Wenn Sie die Teammitglieder dazu ermutigen, sich gegenseitig um Erklärungen zu bitten, schaffen Sie meist ein selbstausgleichendes System. wo verschiedene Teammitglieder sich gegenseitig "automatisch anpassen".

Dies ist größtenteils eine Erweiterung der Antwort von tdammers, führt jedoch in regelmäßigen Abständen Codeüberprüfungen durch.

Wenn er (und andere Entwickler) sich hinsetzen, ihren Code durchgehen und sich mehr oder weniger vor ihren Vorgesetzten und Kollegen verteidigen, werden alle besser programmieren und in relativ kurzer Zeit einen echten Mehrwert schaffen. Kurzfristig wird der betreffende Entwickler keine Entschuldigung dafür finden, seinen Code zum Zeitpunkt der Überprüfung ordnungsgemäß zu kommentieren.

EDIT: Ich bin mir nicht sicher, warum jemand meinen Vorschlag ablehnt - vielleicht habe ich angenommen, dass die Vorteile der Codeüberprüfung allgemein bekannt sind ... Bitte lesen Sie diesen Thread als Community-Analyse der Praxis:

Prüft der Code bewährte Verfahren?

In Anbetracht der oft extremen Ansichten zum Kommentieren zögere ich, nachzudenken. Davon abgesehen ...

Welche Argumente kann ich vorbringen, wenn Sie (nicht lesbaren) Code schreiben, der ordnungsgemäß dokumentiert werden sollte?

Das Schreiben von wartbarem und lesbarem Code erfordert Zeit, Übung und Erfahrung. Unerfahrene Programmierer (und leider auch viele erfahrene) leiden häufig unter dem Ikea-Effekt ( PDF ). Das liegt daran, dass sie es erstellt haben und mit ihm bestens vertraut sind, und sie sind sich sicher, dass der Code nicht nur großartig, sondern auch lesbar ist.

Wenn die Person ein großartiger Programmierer ist, ist kaum Dokumentation erforderlich. Die meisten Programmierer sind jedoch nicht großartig und ein Großteil ihres Codes wird in der Abteilung "Lesbarkeit" leiden. Das mittelmäßige oder sich entwickelnde Programmierpersonal zu bitten, "ihren Code zu erklären", ist nützlich, da es sie dazu zwingt, ihren Code kritischer zu betrachten.

Bedeutet dies, ihren Code zu "dokumentieren"? Nicht unbedingt. In der Vergangenheit hatte ich mit diesem Problem einen ähnlichen Programmierer. Ich zwang ihn zu dokumentieren. Leider war seine Dokumentation so unkenntlich wie sein Code und fügte nichts hinzu. Rückblickend wären Code-Reviews hilfreicher gewesen.

Sie (oder ein Delegierter) sollten sich mit diesem Programmierer zusammensetzen und einen Teil seines älteren Codes aufrufen. Nicht die neuen Sachen, die er kennt, wenn er nur daran arbeitet. Sie sollten ihn bitten, Sie mit minimaler Interaktion durch seinen Code zu führen. Dies könnte auch eine separate "Dokumentations" -Sitzung sein, in der er seinen Code schriftlich erklären soll. Dann sollte er Feedback zu besseren Ansätzen bekommen.

Nebenbei bemerkt ... manchmal wird eine Dokumentation benötigt, unabhängig davon, wie gut die "Lesbarkeit" des Codes ist. APIs sollten über Dokumentation verfügen, extrem technische und komplexe Vorgänge sollten über Dokumentation verfügen, die dem Programmierer hilft, die beteiligten Prozesse zu verstehen (häufig außerhalb des Wissensbereichs des Programmierers), und einige Dinge wie komplexe reguläre Ausdrücke sollten wirklich dokumentieren, womit Sie übereinstimmen.

Viele Projekte erfordern Code-Dokumentation: Schnittstellendokument, Designdokument, ...

Bei einigen Projekten muss diese Dokumentation in Codekommentare eingefügt und mit Tools wie Doxygen, Sphinx oder Javadoc extrahiert werden, damit Code und Dokumentation konsistenter bleiben.

Auf diese Weise müssen Entwickler nützliche Kommentare in Code schreiben, und diese Aufgabe ist in die Projektplanung integriert.

Ich werde erklären, worauf die meisten Antworten und Kommentare hindeuten: Sie müssen wahrscheinlich das eigentliche Problem hier herausfinden, anstatt zu versuchen, Ihre wahrgenommene Lösung durchzusetzen.

Sie sind motiviert, Kommentare in seinem Code zu sehen. warum ? Du hast einen Grund angegeben; warum ist dir dieser grund so wichtig Er ist motivierter, stattdessen etwas anderes zu tun. warum ? Er wird einen Grund angeben; Warum ist ihm dieser Grund so wichtig? Wiederholen Sie diesen Vorgang, bis Sie die Ebene erreicht haben, auf der der Konflikt tatsächlich auftritt, und versuchen Sie, dort eine Lösung zu finden, mit der Sie beide leben können. Ich wette, es hat sehr wenig mit Kommentaren zu tun.

Wenn Sie sich an einen guten Kodierungsstandard halten, ist eine Mindestanzahl von Kommentaren erforderlich. Namenskonventionen sind wichtig. Methodennamen und Variablennamen sollten ihre Rolle beschreiben.

Mein TL empfiehlt mir, weniger Kommentare zu verwenden. Er möchte, dass mein Code verständlich und selbsterklärend ist. Einfaches Beispiel: Variablenname für den Zeichenfolgentyp, der für das Suchmuster verwendet wird

   var str1:String="" //not uderstandable
   var strSearchPattern:String="" //uderstandable

Ich liebe die Antworten auf die Codeüberprüfung, aber vielleicht hilft mein Prozess auch ein bisschen.

Ich liebe Kommentare, aber ich füge sie fast nie beim ersten Durchgang in den Code ein. Vielleicht ist es nur mein Stil, aber während der Entwicklung (Refactoring, Schreiben von Tests usw.) drücke ich drei- bis fünfmal auf denselben Codeabschnitt.

Immer wenn ich etwas verwirrt bin oder wenn mir jemand eine Frage zu einem Codeabschnitt stellt, versuche ich, dies so zu korrigieren, dass es Sinn macht.

Dies kann so einfach sein wie das Hinzufügen eines Kommentars zum Entfernen einer verwirrenden Menge von Operationen in ihre eigene Funktion oder es kann einen größeren Refaktor wie das Extrahieren eines neuen Objekts auslösen.

Ich schlage vor, dass Sie alle Mitglieder der Gruppe dazu ermutigen, sich ihren Code "zu Eigen zu machen", damit er für andere lesbar ist. Dies bedeutet, dass Sie sich jedes Mal, wenn jemand Sie nach Ihrem Code fragt, dazu verpflichten, eine Änderung vorzunehmen - oder noch besser, dies zu tun Person, um die Änderung sofort vorzunehmen!

Erwägen Sie ernsthaft, dies als Teil Ihres "Teamvertrags" zu forcieren (und erstellen Sie auf jeden Fall einen Vertrag, wenn Sie keinen haben) - auf diese Weise haben sich alle darauf geeinigt und Sie haben ihn irgendwo an der Wand, so dass es keinen gibt. Keine Frage, was Sie zugestimmt haben.

Vielleicht muss dieser Typ eine Wertschätzung für gute Codierungsdisziplin erhalten und warum es für andere wichtig ist, den von ihm geschriebenen Code zu verstehen.

Ich habe in meiner Karriere an einigen wirklich schrecklichen Codebasen gearbeitet, bei denen der Code so schlecht organisiert war, Variablennamen so schlecht waren, Kommentare so schlecht oder gar nicht existierten, dass die Codebase meine Produktivität beeinträchtigte. Sie können nicht daran arbeiten, eine Codebasis zu reparieren oder zu verbessern, die Sie nicht verstehen. Wenn diese Codebasis für Neulinge undurchdringlich ist, verbringen sie mehr Zeit damit, sie zu verstehen, als daran zu arbeiten.

Es gibt keinen besseren Lehrer als harte Erfahrung!

In jeder Codebasis lauern einige schreckliche Teile, Teile des Systems, die niemand anfassen möchte, weil er Angst hat, etwas zu beschädigen, oder sie können keine sinnvolle Arbeit daran leisten, weil derjenige, der den Code geschrieben hat, längst abgewichen ist und ihr Verständnis verloren hat des Codes mit ihnen. Wenn dieser Code unkommentiert und nicht selbstdokumentierend ist, macht er die Sache nur noch schlimmer.

Ich schlage vor, Sie finden das Bit Ihrer Codebasis, das so ist, und geben Ihrem lästigen Codierer die Verantwortung dafür. Geben Sie ihm das Eigentum daran, machen Sie es zu seiner Verantwortung und lassen Sie ihn den wahren Schmerz des Arbeitens an Code erfahren, der nicht gewartet werden kann, weil er in kurzer Zeit nicht gut dokumentiert oder unmöglich zu verstehen ist. Nach ein paar Monaten Arbeit bin ich sicher, dass er anfängt, herumzukommen.

Geben Sie ihm einen anderen Code ohne Kommentare und bitten Sie ihn, den Code zu verstehen. Vielleicht versteht er dann die Wichtigkeit von richtigen Kommentaren.

Führt dieser Programmierer eine Codewartung durch? Wenn nicht, sollte er: nach unerwünschten Projekten suchen und ihm die Wartung zuweisen.

In der Regel handelt es sich hierbei um schlecht dokumentierte Projekte, bei denen Sie stundenlang versuchen zu verstehen, was gerade korrigiert wird, was leicht zu korrigieren gewesen sein könnte. Wenn diese Art von Erfahrung ihn nicht auf den neuesten Stand bringen will, wird eine korrekte und nützliche Dokumentation nichts bewirken.

In einem meiner früheren Projekte fehlten Dutzende von Kommentaren (Algorithmus, Ergebnisse oder einige grundlegende JavaDoc-Informationen), und so habe ich beschlossen, 130 Probleme für ihn zu erstellen und ihm alle 4 Tage eine E-Mail-Benachrichtigung über jedes Problem zu senden. Nach 3 Wochen hatte er 280 Probleme, dann beschloss er, Kommentare zu schreiben.

Kommentare haben nur einen Zweck:

Warum macht dieser Code das?

Wenn ein Kommentar nicht erklärt, warum etwas so ist, wie es ist, sollte es entfernt werden. Nutzlose Kommentare, die den Code überladen, sind weniger als nutzlos, sie sind aktiv schädlich.

Ich habe die Angewohnheit, meine Kommentare zum offensichtlichsten Teil meiner IDE zu machen. Sie werden mit weißem Text auf einem grünen Hintergrund hervorgehoben. Das macht wirklich auf sich aufmerksam.

Dies liegt daran, dass der Code erklärt, was etwas tut, und die Kommentare dafür sind, warum es es tut. Ich kann das nicht genug betonen.

Ein gutes Beispiel für einen Kommentar:

/* Must instantiate clsUser before trying to encrypt a password because the code to 
   encrypt passwords only uses strong encryption if that module is loaded. */

Ein schlechtes Beispiel:

/* instantiate clsUser */

Wenn Sie Kommentare als "Abschnitte" des Codes verwenden: Zerlegen Sie Ihre Mammutmethode in kleinere, nützliche benannte Funktionen und entfernen Sie die Kommentare.

Wenn Sie sagen, was Sie in der nächsten Zeile tun: Machen Sie den Code selbsterklärend und entfernen Sie den Kommentar.

Wenn Sie Kommentare als Warnmeldungen verwenden: Stellen Sie sicher, dass Sie den Grund angeben.

Um die Antworten hier zu ergänzen, könnte ich hinzufügen: "Wenn Sie wollen, dass es richtig gemacht wird, müssen Sie es selbst tun."

Ich meine nicht, "Chef-Code-Kommentator" zu werden, ich meine, ein Vorbild zu werden, um zu demonstrieren, was Sie von diesem anderen Entwickler erwarten. Sie sagen , dass das Zeigen effektiver ist als das Erzählen . Wenn Sie den Nutzen von Qualitätskommentaren demonstrieren oder diesen anderen Entwickler sogar als Mentor unterstützen (sofern er dies wünscht), werden Sie möglicherweise mehr Erfolg bei der Annahme von Codekommentaren haben.

In ähnlicher Weise gibt es zu Hause einige Haushaltsaufgaben, die ich nicht gerne mache. Allerdings sind diese Aufgaben zufällig die "pet peeve" -Aufgaben meiner Frau ... Aufgaben, die erledigt werden müssen , damit sie glücklich ist. Die gleiche Situation gilt umgekehrt. Möglicherweise müssen Sie akzeptieren, dass dieser andere Entwickler andere Prioritäten als Sie hat und nicht in allen Punkten mit Ihnen übereinstimmt. Die Lösung, die meine Frau und ich gefunden haben, ist, dass wir für diese "Haustier-Ärger" -Aufgaben einfach selbst vorgehen müssen, auch wenn dies bedeutet, dass wir ein bisschen mehr auf eigene Faust arbeiten müssen.

Einfach: Wenn der Mitarbeiter keine Kommentare abgibt, fordern Sie ihn auf, shift+alt+jbei jeder Methode gleichzeitig mit der Eingabe des Codes auf Auto-Kommentar zu drücken . Bitte überarbeiten Sie den Code, um diese Probleme zu vermeiden.