Wie Menschen zu überzeugen, zu kommentieren Ihren code [geschlossen]

https://stackoverflow.com/questions/159597

03-07-2019
|

Frage

Was sind gute Argumente, um andere davon zu überzeugen, zu kommentieren Ihren code?

Ich merke viele Programmierer bevorzugen die wahrgenommene Geschwindigkeit des Schreibens von code ohne Kommentare über verlassen einige Unterlagen für sich selbst und andere.Wenn ich versuche, Sie zu überzeugen, ich bekomme zu hören, unausgegorenes Zeug wie "die Methode/Klasse name sollte sagen, was es tut", etc.Was würden Sie sagen, Ihre Meinung zu ändern?

Wenn Sie gegen kommentieren Sie bitte einfach Kommentare hinterlassen.Dies soll eine Ressource für die Menschen, die versuchen, die Menschen zu überzeugen, zu kommentieren, den code, sonst nicht.:-)

Andere Fragen sind: Kommentieren von code, Tun Sie kommentieren Ihren code und Wie würden Sie Ihre Kommentare wie.

Lösung

Der beste Weg, um eine Person zu überzeugen ist, sie es auf eigene Faust zu machen zu realisieren. Machen Sie sie debuggen gut kommentierten Code. Es wird ihnen zeigen, was gut zu kommentieren aussieht - Kommentare sind nichts, wenn sie nicht wirklich relevante Informationen vermitteln (die in der Regel nach dem „Warum“ ist, weil der Code beschreibt das „Was“). Sie werden feststellen, wie einfach es ist. Dann lassen Sie sie einige ihrer alten Code zurück. Sie werden feststellen, wie schwer es ist. Sie haben sie nicht nur gezeigt, was nicht zu tun, aber was zu tun ist (dies ist wichtiger). Sie müssen nicht mehr tun. Was mehr ist, man muss sich verbal nicht versuchen und zu überzeugen. Sie müssen einfach verstehen die Notwendigkeit, Code auf ihre eigene Weise zu äußern. Dies ist natürlich davon aus, dass der Code, der kommentiert werden muss, ist nicht selbsterklärend.

Andere Tipps

Nur eine kurzen Kommentar zum „Warum“ und nicht das „Was“. Soweit ich stimme, sollte es von der Klasse oder Methode oder Variablennamen klar sein, was sie tut und was wird es angewendet. Umgestalten, wo dies nicht der Fall, statt sie zu kommentieren.

Wenn Sie diesen Ansatz nehmen, werden Sie Kommentare, und Sie werden nützliche Kommentare. Programmierer mag zu erklären, warum sie etwas tun.

Zeigen Sie ihnen, ihren eigenen Code von 6 Monaten vor. Wenn sie nicht genau verstehen und darlegen, welche es innerhalb von 2 bis 4 Minuten der Fall ist, hat Ihr Punkt wahrscheinlich gemacht worden.

Meine Meinung:

würde ich nicht. Die Methode / Klassenname sollte sagen, was sie tut. Wenn dies nicht der Fall, entweder das Verfahren oder der Klasse versucht, zu viel zu tun, oder es ist schlecht benannt.

Ich bin ein Fan von zu kommentieren, warum nicht, was. Wenn es nicht klar ist, warum Code ein Ansatz über eine andere Verwendung, kommentieren sie. Wenn Sie einen Hack nicht verwendetes Variable hinzuzufügen haben um einen Compiler Fehler zu erhalten, kommentieren, warum. Aber Kommentare wie „// Mit Datenbank verbinden“ sind Zeichen von fehlerhaftem Code oder schlechte Politik. Ein Verfahren namens ConnectToDatabase () ist viel besser. Und wenn es „// Ermitteln DB-Server-IP“ in ihm, vielleicht, dass ein Verfahren herausgezogen genannt werden sollte „DetermineDbServerIPAddress ()“.

Entwurf kann dokumentiert werden, aber Kommentare sind ein allgemein ein schlechter Ort für diese Ebene der Dokumentation. Mit der Kenntnis des Designs und einigen Kommentaren darüber, warum das, was und wie sollte klar sein. Wenn es nicht, anstatt davon zu überzeugen, ihren Code zu kommentieren, bekommen sie es zu verbessern.

Vielleicht ist es nur etwas, das aus der Erfahrung gelernt werden muss; Insbesondere die Erfahrung der nach sechs Monaten zurück zu Ihrem eigenen Code kommt, und versuchen, was zum Teufel zu arbeiten, Sie dachten (oder was Sie waren), wenn Sie es geschrieben haben. Das überzeugte mich sicher, dass die Kommentare waren nicht so eine schlechte Idee.

Geben Sie ihnen einige (~ 500 Zeilen, Minimum) schrecklich, unkommentiert Spaghetti-Code Refactoring. Stellen Sie sicher, dass Variablen nicht logisch benannt. Leer optional.

Und wie sie like it!

Allzu hart, aber es bekommt zwei Punkte über in einem Rutsch.

Schreiben Sie Ihren Code gut.
Kommentar es so Sie und andere wissen, was es bedeutet.

soll ich betonen, dass dieser Code sollte nicht von ihnen stammt. Kommentare ist wirklich nützlich für Ihren eigenen Code, Monate auf der ganzen Linie zu verstehen, aber sie sind auch fast-on für das Verständnis komplexe Teile von anderen Menschen Code. Sie müssen verstehen, dass jemand anderes könnte müssen verstehen, was sie tun.

Eine letzte edit: Kommentar Qualität ist auch ziemlich wichtig. Einige Entwickler haben ein fast 2: 1-Code-zu-Kommentar-Verhältnis in ihrer Arbeit, aber das macht sich nicht gut Kommentare zu machen. Sie können überraschend wenige Kommentare in Ihrem Code haben und noch haben es sehr viel Sinn machen.

Erklären Sie , was Sie tun . Ihr Code-Qualität sollte haben die meisten dieser Arbeit für Sie aber.
Noch wichtiger ist, zu erklären , warum Sie etwas tun ! Ich habe so viel Code gesehen, der genau sagt, was etwas ohne wirkliche Idee tut, warum der Entwickler (leider mich die meiste Zeit) hielt es für eine gute Idee, in erster Linie war.

Erinnern Sie sie, dass die Code-Lese nur ihnen sagen kann, was der Code hat , nicht das, was es ist sollte zu tun.

Wenn Sie oder die anderen Entwickler haben nicht-Code lesen Complete (oder Code Complete 2 ) noch dann stoppen, was Sie tun und lesen.

Eine Sache, die standands out ist „Eine Funktion nur eine Sache tun sollte und tun es auch.“ wenn eine solche Funktion nach der einen Sache gestattet es tut gut, was weitere Notwendigkeit besteht für einen Kommentar?

Kommentare haben die Gewohnheit, mit dem Code nicht synchron gehen sie eigentlich sind beschreiben werden. Das Ergebnis kann schlimmer sein als den ursprünglichen Kommentar in erster Linie mit. Nicht nur, dass aber die Entwickler wissen , dass die Kommentare altern können und nicht trauen kann. Daher werden sie den Code und erkennen für sich selbst lesen, was es eigentlich ohnehin tut! Dieser zunichte macht irgendwie den Punkt die Kommentare dort an erster Stelle setzen.

Having said, dass das gleiche gilt für eine Funktionsname sein kann, kann es auch originaly genannt wurden aber Überstunden neue Operationen wurden hinzugefügt, die im Namen nicht erwähnt werden.

Alle Kommentare scheinen die Codezeilen, ein Entwickler zu tun trennen würde es vorziehen, näher zusammen zu sein, so dass sie mehr pro ganzen Bildschirm sehen können. Ich weiß, dass meine eigene Re-Aktion auf ein Stück Code, mit vielen Kommentaren, die ich habe, zu verstehen. Löschen Sie alle Kommentare. Ich kann es jetzt sehen, was der Code bis zu ist.

Am Ende des Tages, wenn Sie Ihre Zeit gehen verbringen macht die Dinge richtig Ihre Zeit besser ist vorgerückt den Code Refactoring seine als leidlich selbstbeschreibende, um sicherzustellen, wie es eher sein kann als nur das Schreiben Bemerkungen. Eine solche Übung auf andere Weise wie identifing gemeinsame Stücke von Code zahlt sich aus.

Es ist zu bedenken, dass viele gute Entwickler viel lieber schreiben frische saubere C #, Java, was auch immer als die weit weniger präzise menschlichen Sprachen mit allen Annahmen und Unklarheiten, die sie haben. Wahre die meisten Menschen mit gesundem Menschenverstand würde wissen, wie viel Detail ist detailliert genug, aber gute Entwickler sind nicht ‚die meisten Menschen‘. Das ist, warum wir mit Kommentaren wie \\adds a to b and store it in c am Ende (ok das ist zu extrem, aber Sie erhalten den Punkt).

Fragen sie etwas zu tun, sie tun Hass und sind ehrlich gesagt, nicht sehr gut (auch wenn Sie ihr die richtige Sache überzeugt sind, zu tun) ist einfach eine Schlacht schon verloren.

Ich bin nicht snarky dich an, aber Sie sollten die Frage umformulieren sein Wie wollen Sie andere Entwickler überzeugen, als Team zu arbeiten?

Im Ernst, übernehmen einige Leute Sie ihre Gedanken lesen.

Wenn Sie einen Teil eines agilen Team sind, wird Code kollektives Eigentum, also wenn Sie unkommentiert, umständlich zu sehen, oder hart Code zu lesen, gehen Sie vor und ändern (Refactoring) es so verstehen Sie es. Wenn die Leute beschweren sich, ihnen sagen, warum und werden im Voraus. Das fand man es unverständlich, und niemand besitzt den Code.

Unsere Strategie ist systematischen Code-Reviews zu haben, und den Code zu verwerfen, die nicht ordnungsgemäß dokumentiert ist (durch Kommentare, die ordnungsgemäße Funktion Namensgebung und Organisation, etc ...). Wenn es für den Prüfer nicht klar ist, gehen Sie zurück auf die Werkbank, period.

Ich würde sagen, „gestern habe ich einige Code zu lesen hatte. Ich war in der Lage, es zu verstehen, aber weniger als oder gleich 5 gut gewählten Zeilen des Kommentars erklären, wie sie ihre Ziele erreicht hätte mir erlaubt, es zu lesen in etwa die Zeit, ein Zehntel und dann konnte ich stattdessen ein Problem zu verstehen besorgt habe. ich bin nicht dumm, und du bist nicht schlauer, weil man Dinge schreiben kann, die schwer zu verstehen sind. im Gegenteil, wenn Sie können ‚t lesbare Dokumentation + Code Ensembles erzeugen dann sind Sie weniger ein Entwickler."

Ich hatte das in mir gebohrt schon vor langer Zeit: Wenn Sie etwas und jemand vernünftiger Fähigkeit schreiben kann es nicht verstehen, dann ist es deine Schuld, seine nicht Schuld. Dies gilt in natürlichen Sprachen zu schreiben, und es gilt in Programmiersprachen geschrieben werden.

Es wurden ähnliche Diskussionen über kommentieren. Hier ist die eine auf welchen Regeln Menschen folgen, wenn der Code zu kommentieren: Was sind Ihre „harten Regeln“ über Ihren Code? kommentieren. Einige Antworten haben auch sehr gute Gründe, warum Sie wollen würde, um Ihren Code zu kommentieren.

Zeigen Weisheit in Ihrem Wunsch nach Kommentaren und sie werden eher hören.

Weniger ist mehr.

Betonen Qualität vor Quantität.

In meinem Team gab es einen Push alles in bestimmten API Stellung zu nehmen. Einige Entwickler begannen mit einem Werkzeug, das automatisch Kommentare, indem man der Methode Namen und Unterschriften erzeugen würde.

Zum Beispiel:

/// <summary>
/// Gets the Person.
/// </summary>
/// <returns>
/// A Person
/// </returns>
public Person GetPerson()
{

}

Können Sie sich eine größere Verschwendung von Bildschirm Immobilien? Können Sie sich eine größere Verschwendung von Gehirnzyklen denken als Kommentare zu lesen, die keine neuen Informationen zur Verfügung stellen?

Wenn es offensichtlich aus der Methodensignatur ist, sagen Sie es nicht! Wenn ich es aus in wenigen Sekunden herausfinden kann, kann es nicht in einem Kommentar setzen. Wie andere es gesetzt haben, sagen Sie mir, Warum Sie gewählt haben, es so zu tun, nicht was Sie haben. Schreiben Sie Ihren Code, so dass es offensichtlich ist, was es tut.

Mit dem Beispiel. Die Entwickler sind leicht beeinflussen, wenn sie die richtige Sache zu sehen, die so solide Praktiken in Aktion zu sehen fördern können sie das gleiche zu tun. Darüber hinaus können Sie Ihre Gruppe ermutigen, Code-Metriken zu verabschieden, die Code Wartbarkeit und Kommentare richten. Zum Beispiel wird Code-Analyse einen Fehler für Methoden ohne Zusammenfassung Dokumentation erzeugen.

Die aktuellen Coding-Standards an meinem aktuellen Ort der Arbeit ist es, jede Funktion zu kommentieren. Blanked Regeln wie diese sind schädlich und sollten nie an Ort und Stelle sein. Es gibt Situationen (und einige von ihnen häufig), wo das Hinzufügen von Kommentaren entfernt Lesbarkeit.

class User {
    getUserName() { /* code here */ }
}

Was ist der Punkt, eine Funktion Header an den oben peice Code in das Hinzufügen? Was wollen Sie besdies sagen „bekommt den Benutzernamen“. Nicht alle Code muss kommentiert werden. Meine Faustregel ist:. Überspringen Sie die Kommentare, wenn Sie nicht hinzufügen, alle nützlichen Informationen, dass die Funktion Signatur nicht

Kommentare sollten auf der Ebene der Absicht (warum nicht, wie), und selten gründlich, geschrieben sein.

Wenn das Schreiben von Code Ich neige dazu, ziemlich stark wie selbstverständlich zu kommentieren. Dann gehe ich zurück durch und versuchen, so viele Kommentare wie möglich zu löschen, ohne die Verständlichkeit des Codes zu verringern. > 80% der Zeit eine gut benannte Methode als Extraktions das ist so einfach, führt dies in der Regel in einem Kommentar, die die Informationen in dem Code selbst nur dupliziert. Darüber hinaus, wenn es ein Abschnitt des Codes ist, dass „muss“ ein Kommentar, den ich nach Wegen suchen, um es zu vereinfachen oder es deutlicher zu machen.

Der Code sollte selbsterklärend sein und mit den richtigen Techniken 95% der Art und Weise bekommen kann es ziemlich leicht. Generell halte ich es für einen Fehler, wenn es irgendwelche Kommentare zu Code noch, dass ich einchecken.

Abhängig von, wie viel Energie Sie haben ...

fand ich eine sehr effektive Art und Weise es ein fester Bestandteil von Peer basierten Code-Reviews zu machen war - Punkte für Kommentare. Wenn es eine Bemerkung war, dass der Code schlecht kommentiert wurde würde ich der Entwickler machen einen Kommentar zu meiner Zufriedenheit, die im Grunde meanth sie genug des Codes beschreiben musste für mich verstehen, indem es Druck aus und lesen. Und ich würde tun.

Bemerkenswert war beliebt bei den Entwicklern, obwohl es dickensian klingt. Zwei Dinge geschehen. Zunächst begannen die Menschen, ihren Code zu kommentieren. Zweitens schlecht kommentierte Code wurde ein Zeichen, dass der Entwickler nicht ganz verstehen, was sie geschrieben hatte (sonst würden sie es beschrieben haben).

Der einzige Nachteil war, dass die Kommentare mit dem Code gehalten werden mußten, wenn es für Fehlerbehebung wurde überarbeitet usw. Das war fast unmöglich, in einem realen Entwicklung Shop zu erzwingen, aber sobald genug gute Praxis war es irgendwie engrained von passiert natürlich.

BTW ziehe ich Kommentare in dem Code selbst eher als ein Dostojewskis Roman als doc-String. Ersteres ist eine nützliche Hilfe für nachfolgende Programmierer. Letzteres ist nur ein langes Stück veraltet Text, der die Dokumentation füllt und verleitet jeden etwas dabei.

Haben sie eine unbekannte API verwenden, aber tun, um die Programmierung auf einem Nicht-Internet angeschlossenen Maschine (wenn man sie in diesen Tagen finden können), so dass sie haben keinen Zugriff auf die API-Dokumentation. Dies ist effektiv, was sie andere Entwickler zwingen zu tun, wenn sie den Code der nicht-Dokumentaristen versuchen, zu verwenden!

Man muss auch unterscheiden zwei verschiedene Kommentare hier:

API Kommentare (javadoc oder andere ähnliche Art von Dokumentation):Sie können Fragen, für Sie verwenden Sie Ihren eigenen code in eine limit-Szenario (Randbedingungen wie null-Objekten oder leere Zeichenfolgen oder...) und sehen, ob Sie es tatsächlich schaffen, sich zu erinnern, was hat Ihre eigenen Funktionen in diesen Fall,
(Deshalb bin ich für eine eine vollständige javadoc-einschließlich limit-Wert)
Interne Vermerke (innerhalb des Quellcodes):Sie können Sie bitten, zu erklären, die Funktion, die Sie programmiert haben, nur wählen Sie eine Funktion mit einem wirklich hohe zyklomatische Komplexität, und sehen, wie Sie kämpfen, um all die verschiedenen code-workflows und die Entscheidung Verzweigung ;)

Nun, es gibt immer die „wenn Sie Ihren Code nicht kommentieren, werden wir jemanden finden, der ihnen kommentieren werde“ -Ansatz.
sanfter, ihnen sagen, dass sie schwer im Stich lassen die Team, wenn sie dokumentieren und kommentieren nicht, was sie tun. Der Code gehört nicht zu den einzelnen, es sei denn, sie vollständig einsame Wölfe sind. Es gehört zu dem Team, die Gruppe, wäre es ein Unternehmen oder eine Gemeinschaft sein.

"Das Schreiben von Code" = "Schreiben Folge von Befehlen in einer speziellen Sprache" + "Schreiben Kommentare"

Es ist selbstverständlich, seinen Code kommentieren, während es zu schreiben! Haben Sie jemals Code kommentiert, die bereits 3 oder 4 Monate alt ist? (Natürlich haben Sie, und es war alles andere als Spaß!)

Wenn Ihr Projekt ist bereits gut dokumentiert, Programmierer, den neuen Code hinzufügen können motiviert werden, um Kommentare zu schreiben in ähnlicher Weise.

@James Curran I 100% zustimmen! Ich kann den Code lesen und herauszufinden, was Sie den Compiler gesagt, zu tun; aber das bedeutet nicht, es war Ihre Absicht der Compiler tun zu machen. Ich weiß, ich bin kein arrogent genug Programmierer, dass jedes Mal wenn ich Code schreiben, zu glauben, es tut genau das, was ich versuche, es zu tun zu machen. Außerdem finde ich oft es mir, indem Sie durch dummen logischen Fehler in meinem Code fangen hilft, nachdem ich es geschrieben habe und versucht zu erklären, was ich wollte für den Code tun.

Eine Idee ist, darauf zu hinweisen, dass es weniger als eine Minute dauert ein oder zwei Sätze pro Klasse zu schreiben und weniger als eine halbe Minute ein Satz pro Methode zu schreiben.

Sagen Sie ihnen, ihre Funktionen und Schnittstellen mit Javadoc commments zu dokumentieren und dann den Code durch Doxygen laufen cool aussehende HTML-Dokumentation für ihren Code zu generieren. Der Coolness-Faktor kann manchmal einen guten Motivator sein.

Ich verwende eine subtile Technik:

habe ich die Ebene der Warnungen im Projekt als Fehler gemeldet werden. Und unser Continuous Integration Server baut die gesamte Lösung zusammen mit XML-Dokumentation bei jedem ckeck-in.

Wenn die Entwickler nicht die Kommentare schreiben, schlägt der Build! Und danach müssen sie die Kommentare schreiben, so dass nach einer Weile wurde sie daran gewöhnt.

Es ist nicht aggressiv in Bezug auf Druck, aber ich finde es so schön, Art und Weise, ihr Verhalten zu korrigieren.

Wenn Entwickler Teil in Code-Reviews nehmen und sind gut ausgesetzt kommentieren sollten sie in der Lage sein, den Schlüssel zu bekommen. Wenn sie nicht die Praxis als nützlich sehen, dann sollten sie ein Feedback von ihren Gutachtern erhalten.

, dass Failing (vorausgesetzt, du bist der Supervisor / Manager) machen es Teil ihrer Leistungsbeurteilung. Wenn Sie es messen kann, kann man darauf basierende bewerten.

Stellen Sie sicher, dass es ein PRüFTE kommentieren, dass Sie Gäste auf, wie die passiv-aggressive Devs wird jede letzte Aussage als nicht-so-subtile FU dokumentieren.

Ich habe fest davon überzeugt werden, in was ich als Headrick-Regel , für einen Mitarbeiter von mir benannt, der entdeckt, dass ein guter Weg, um jemanden zu motivieren, etwas zu tun ist, um es für sie schmerzhaft < em> nicht , es zu tun.

In Ihrem Fall fragen Sie Ihren Nicht-Kommentierung Entwickler eine oder zwei Stunden zu erklären, ihren Code zu verbringen, vielleicht zu einem „langsamen“ Publikum, vielleicht in der Mittagspause „Projekt Abrutschen zu vermeiden“ wird einen langen Weg gehen. Intelligente Menschen - auch hartnäckig diejenigen - lernen schnell

Meiner Meinung nach (und ich spreche von .NET-Programmierung hier), wenn Sie einen Kommentar setzen müssen Sie bei der Herstellung der Code lesbar sind gescheitert. Die Antwort ist in der Regel Umgestalten!

Wenn Sie jedoch das Gefühl haben Sie einen Kommentar setzen, dann sollte es immer sein, ein „Warum“ Art von Kommentar und kein Kommentar, der erklärt, was der Code tut.

Das Aufschreiben, was eine Methode / Klasse, bevor sie tatsächlich tun Codierung es viel hilft es richtig zu machen -. Und Sie haben es kommentiert

Nur gute Ingenieure beschäftigen, die ihr Code gewährleisten implizit die Absicht erklärt (mit Kommentaren und aus anderen Gründen). Jeder, der einen Job will, muss es richtig machen. Hart, aber fair, IMHO.

Lizenziert unter: CC-BY-SA mit Zuschreibung

Nicht verbunden mit StackOverflow