Mein Kunde möchte 25% der Kommentare in meinem aktuellen Projekt, wie soll ich reagieren? [geschlossen]

96

Nachwuchsentwickler hier.

Ich arbeite zurzeit alleine an einer Webanwendung für einen großen Kunden meines Unternehmens. Ich habe letzten Monat angefangen. Der Kunde möchte mindestens 25% der Kommentare in jedem seiner Softwareprojekte.

Ich habe den Code früherer Anmeldungen überprüft und hier meine Beobachtungen:

  • Jede Datei beginnt mit einem Kommentarblock (Paket, Datum der letzten Aktualisierung, Name meines Unternehmens und Copyright)
  • Alle Variablen werden mit ihren Namen kommentiert // nameOfCustomer public String nameOfCustomer

  • Alle Getter und Setter sind kommentiert

  • sehr wenige nützliche Kommentare

Es scheint, als würden Entwickler so viele Kommentare wie möglich abgeben, um diese 25% -Schwelle zu erreichen, unabhängig von Qualität und Nützlichkeit. Meine Firma sagt mir, dass "wir es tun, wie der Kunde es will".

Ich habe nicht direkt mit dem Kunden darüber gesprochen. Hier sind meine bisherigen Argumente:

  • unnötige Zeilen zum Lesen und Schreiben (Zeitverschwendung)
  • Kommentare werden manchmal nicht aktualisiert (Quelle der Verwirrung)
  • Es ist weniger wahrscheinlich, dass Entwickler wirklich nützliche Kommentare verwenden oder ihnen vertrauen

Was raten Sie zu diesem Thema? Wie soll ich mit der Situation umgehen?

Robin_
quelle
162
Das ist lächerlich. Wenn der Kunde dies jedoch wünscht und er Ihnen gutes Geld dafür zahlt, dann geben Sie ihm dieses Geld.
Robert Harvey
20
25% der Zeilen (dh Sie haben nie einen Kommentar in dieselbe Zeile wie der Code geschrieben) oder 25% der Bytes ?
RonJohn
6
Im Wesentlichen das gleiche Geschwätz wie in Mein Chef will eine erzählte zeilenweise englische Erklärung unseres Codes
gnat
10
Sei hier besser vorsichtig. Normalerweise gibt es einen Grund für diese Art von Erwartung ... Wenn Sie Ihrem Kunden mitteilen, dass diese Kommentare nutzlos sind, möchte er / sie möglicherweise immer noch 25% der Kommentare (aus welchem ​​Grund auch immer), aber jetzt OHNE die, die Sie als nutzlos bezeichnen. Sie befinden sich möglicherweise in größeren Schwierigkeiten ... Manchmal werden
Kundenargumente
19
Dies ist eine Objektstunde in einer Regel, die Sie in Ihrer Karriere reichlich beobachten können: Die Sache, die Sie messen, ist die Sache, die Sie bekommen . Sie haben eine Metrik für Kommentare erhalten, daher erhalten Sie Kommentare. Ein vernünftigerer Kunde würde Ihnen Metriken für Leistung, Korrektheit, Robustheit und Kosten geben, und dann würden Sie diese Dinge erhalten. Aber Sie haben keinen vernünftigen Kunden.
Eric Lippert

Antworten:

115

Alle anderen Antworten und Kommentare hier haben mich wirklich auf die Palme gebracht, weil sie meiner ersten Reaktion und der Haltung, die ich in meinen Kollegen gesehen habe, so entgegengesetzt sind. So würde Ich mag einen alternativen Ansatz beschreiben, wenn auch nur zum Wohl des Seins der abweichenden Stimme .

Das Leitmotiv dieser Antwort lautet: "Den Kunden begeistern". Den Kunden zu begeistern bedeutet nicht nur, seine Erwartungen zu erfüllen. Es bedeutet, dass Sie ihre Anforderungen so genau verstehen, dass Sie ihre Aussagen so interpretieren können, wie sie es bedeuten, und über das hinausgehen, was sie verlangen. Andere Antworten scheinen sich an dem Prinzip der böswilligen Einhaltung zu orientieren, das ich für abscheulich halte. und außerdem ist die Geschäftspraxis fragwürdig, da es ein schlechter Weg ist, Stammkunden zu gewinnen.

Für mich ist das der Anfang eines Dialogs, wenn ich den Kunden sagen höre: "Ich möchte 25% Kommentare". Für mich ist klar, dass die Implikation hier lautet: "Ich möchte viel beschreibenden Text, damit Neulinge in dieser Codebasis schnell zum Laufen kommen", nicht: "Ich möchte, dass Sie Zufälligkeiten in einer bestimmten syntaktischen Kategorie hinzufügen" als andere Antworten scheint es zu nehmen. Und ich würde diese Bitte ernst nehmen und beabsichtige, viele deskriptive, hilfreiche Kommentare zu verfassen, einen Neuling in die Struktur des Codes einzuführen, auf überraschende technische Entscheidungen hinzuweisen, die Gründe zu erläutern und hochrangiges Englisch zu vermitteln Beschreibungen von komplizierten Codeabschnitten (auch wenn sie keine Überraschungen haben). Diese Absicht und dieses Verständnis sind der Ausgangspunktder Diskussion - das ist, bevor wir überhaupt anfangen zu reden. Für mich ist die Implikation der Anfrage so klar, dass es nicht einmal dieser Klärung bedarf; aber wenn es dir unklar ist, solltest du dich natürlich bei ihnen melden!

Okay, wohin geht der Dialog, wenn das der Ausgangspunkt ist? Der nächste Teil des Dialogs sieht folgendermaßen aus:

  1. Ich würde erwarten, dass dies eine ernsthafte zusätzliche Anstrengung ist, möglicherweise in einer zweiten Phase des Projekts, die über die Produktion des Werkzeugs hinausgeht, für das sie sich interessieren. Es kann einige Minuten dauern, diesen Prozess zu diskutieren und zu erklären, warum es zusätzliche Arbeit ist, aber ich werde es hier weglassen, weil ich als professioneller Programmierer erwarte , dass Sie wissen, wie schwierig es ist, gute Kommentare abzugeben.
  2. "Eine ernsthafte zusätzliche Anstrengung" bedeutet, dass wir möglicherweise ein längeres Zeitbudget und ein größeres Geldbudget benötigen. oder wir müssen möglicherweise das Funktionsbudget reduzieren; oderMöglicherweise müssen wir bei der Qualität und Quantität der Kommentare Kompromisse eingehen. Dieser Teil wird ein bisschen wie eine Verhandlung sein. Aber meiner Meinung nach sollten Sie die Kosten für diese zusätzliche Arbeit sehr genau einschätzen und sicherstellen, dass dies für den Kunden ein so wichtiges Merkmal ist, dass er bereit ist, diese Kosten zu übernehmen. Und wenn doch - toll! Sie erhalten zusätzliche Zeit und Geld, und sie erhalten hochwertige Kommentare. Jeder gewinnt. Und wenn sich herausstellt, dass die Kommentarfunktion für sie nicht so wichtig ist, dass sie bereit sind, die Fähigkeit zum Flurgeln von Widgets zu verlieren oder die Frist bis zum späten Granuary 20x6 zu verschieben, dann gewinnt jeder erneut: Sie erhalten das Produkt, das sie haben möchten, und Sie müssen nicht den zusätzlichen Aufwand aufwenden, der erforderlich ist, um qualitativ hochwertige Kommentare zu erstellen.

Hier ist, wo ich denke, der Dialog sollte nicht gehen:

  1. Drohen Sie dem Kunden nicht mit minderwertigen Kommentaren. Lassen Sie sich von ihnen bei der Auswahl des Aufwands helfen, den sie aufwenden möchten und für den sie bereit sind, zu zahlen. Versprechen Sie ihnen keine 25% -Kommentare und teilen Sie ihnen dann mit, dass Sie dieses Versprechen einhalten möchten, indem Sie nach der Erstellung des Projekts automatisch Zufälligkeiten generieren.
  2. Verstecke deine Pläne nicht. Versprechen Sie ihnen keine 25% -Kommentare und generieren Sie dann automatisch Zufälligkeiten, ohne ihnen mitzuteilen, dass Sie das tun werden. Wenn sie es bemerken (nicht wenn), verlieren Sie beide viel: Sie sind unzufrieden mit dem Produkt, das sie bekommen, und Sie bekommen eine negative Mundpropaganda.
  3. Versuchen Sie nicht, sie davon zu überzeugen, dass sie keine Kommentare wollen. Sie wollen eindeutig Kommentare. Diskutieren Sie die Kompromisse verschiedener Ansätze: Ja! Diskutieren Sie alternative Möglichkeiten, um die Codebasis für Neulinge benutzerfreundlich zu gestalten: Ja! Sagen Sie ihnen, dass sie nicht wissen, was sie wollen: wie, nein. Sie möchten mit ihnen zusammenarbeiten, um das zu erreichen, was sie wollen. Verstehen Sie also, was das ist, und finden Sie heraus, wie Sie dies in einem Budget, das sie billigen, am besten umsetzen können. Priorisieren Sie dabei die Funktionen, die ihnen am wichtigsten sind, wenn die verfügbaren Ressourcen nicht ausreichen.
  4. Machen Sie keine Ausreden darüber, wie schwer es ist, Kommentare zu schreiben. Das Schreiben von Code ist schwierig. Debugging-Code ist schwer; Kommentare zu schreiben ist schwierig. Wenn es einfach wäre, würden sie dich nicht einstellen. Überspringen Sie einfach die Beschwerden und gehen Sie direkt zu dem Punkt, den sie interessieren, nämlich wie sich der zusätzliche Aufwand auf sie auswirkt.
Daniel Wagner
quelle
3
Nizza positiv auf die Frage zu nehmen :-)
cmaster
9
@ThorstenS. Das Unternehmen, für das ich arbeite, leistet einen Großteil seiner Arbeit für die Verteidigungsindustrie. Vielleicht möchten Sie Ihre psychischen Kräfte überprüfen lassen. Außerdem habe ich nie gesagt, "interpretiere ihre Wünsche nicht so, wie sie sie geschrieben haben": Ich würde "25% Kommentare" als ernsthafte, aber zufällige Anfrage behandeln - die eigentliche Anfrage ist "eine große Menge technischer Texte", und 25% sind es Nur ein Hinweis auf den Aufwand, den sie für diesen Körper erwarten, wahrscheinlich willkürlich gewählt, aber dennoch ein Ziel, das Sie nicht verpassen sollten.
Daniel Wagner
12
Wenn ich einen Programmierer einstellen würde, wäre Herr Daniel Wagner der Typ, den ich gerne einstellen würde.
Joe Gayetty
5
Dies ist eine großartige Antwort, da die Absicht der Anfrage im Gegensatz zum Brief der Anfrage identifiziert und angesprochen werden soll. IMO Dies ist der Unterschied zwischen einem Entwickler und jemandem, der nur Code schreibt.
Justin Ohms
6
Es wäre auch gut, ausdrücklich darauf hinzuweisen, dass diese Kommentare die Wartungskosten erhöhen . Einmal erstellt, müssen sie ständig aktualisiert werden , oder sie sind eine Verschwendung von Zeit und Geld. (Warte bis morgen auf +1, damit du die Repräsentanten bekommst.;) Du hast es verdient.)
jpmc26
83

Der Kunde ist König. Als Auftragnehmer müssen Sie alle Anforderungen erfüllen, die der Auftraggeber als Qualitätsstandard definiert hat. Oder du riskierst, draußen zu sein.

Vor diesem Hintergrund ist es sehr wichtig, wie die (hier schlechten) Qualitätsstandards definiert werden:

  • Vertragliche Qualitätsstandards: Der gelieferte Code muss den Anforderungen entsprechen oder es liegt eine Vertragsverletzung vor. Keine Wahl.

  • Formale Unternehmensqualitätsstandards: Auch wenn der Code perfekt funktioniert, wird er von so vielen Leuten als schlechte Qualität eingestuft, dass Sie alt werden, bevor Sie alle in eine bessere Praxis umgewandelt haben. Schlimmer noch: Mit bekannten Tools können solche Qualitätsmetriken (z . B. Sonarwürfel ) automatisiert und legitimiert werden . Fast keine Wahl.

  • Ad-hoc-Kriterien, die von mehreren Personen beim Kunden festgelegt wurden. Hier könnte man sich austauschen. Es gibt Hoffnung :-)

In diesem letzten Fall könnte es eine gewisse Flexibilität geben, und Sie könnten versuchen, diplomatisch darauf hinzuweisen. Hier einige Argumente, die gegen die Kriterien des Kunden sprechen:

  • Produktivitätsproblem: Die Codierung erfolgt zweimal (einmal in Englisch und einmal in Code).
  • Genauigkeitsproblem: Wenn Änderungen am Code vorgenommen werden, müssen diese in den Kommentaren vorgenommen werden, da sonst die Kommentare möglicherweise unbrauchbar werden.
  • Refactoring-Problem: Da das Refactoring-Tool die Variablennamen in Kommentaren nicht verarbeitet.
  • Risikoproblem: Mehrdeutigkeit (oder Überalterung) von Kommentaren kann Verwirrung stiften und das Risiko erhöhen, dass Fehler auftreten.
  • Quantität ist nicht Qualität
  • Diese lustige Sammlung nutzloser Kommentare zu StackOverflow .
  • Dieser Artikel argumentiert, dass eine hohe Kommentarquote sogar ein Anzeichen für einen Codegeruch sein könnte.

Aber anstatt gegen das Böse zu sprechen und den Kunden zu konfrontieren, könnte man einfach bessere Ansätze fördern:

  • Sauberer Code (schlagen Sie Ihrem Kunden das Buch vor: Es gibt einen überzeugenden Abschnitt mit Kommentaren und selbstdokumentierendem Code).
  • Dokumentationspraxis: Die schwierigsten Dinge zu erfassen und damit die wertvollsten Informationen, wie zum Beispiel die Beziehung und Interaktion zwischen Klassen, werden besser in einem separaten Dokument dokumentiert (zum Beispiel in einem UML-Bild anstelle von 1000 Kommentarwörtern?).

Wenn der Kunde immer noch nicht überzeugt ist, können Sie eine experimentelle Alternative vorschlagen, indem Sie mithilfe von Tools automatisch eine Dokumentation mit Kommentaren wie javadocoder generieren doxygen. Schlagen Sie damit vor, den Fokus von Quantität (25% des Codes) auf Qualität zu verlagern (erzeugen Sie einen verständlichen Javadoc).

Christophe
quelle
7
Wenn der Kunde König ist, zeigt dies, wie ineffizient solche Kundenkönigschaften sind!
Steve
82
" Der Kunde ist König. Also müssen Sie als Auftragnehmer alles erfüllen, was der Kunde als Qualitätsstandard definiert hat. Oder Sie riskieren, draußen zu sein. " Das Gegenteil war meine Erfahrung. Wer seinen Kunden das gibt, was er zu wollen glaubt und nicht, was er wirklich braucht, überlebt nicht lange. Tatsächlich reserviere ich diese Form des Missbrauchs nur für echte Problemkunden - und eine zweite Dosis wurde nie benötigt.
David Schwartz
6
@ DavidSchwartz ja, sicher. Manchmal denken Kunden, dass sie etwas brauchen, aber wirklich ein anderes. Bis der Berater oder der Entwickler überzeugt, und 2/3 meiner Antwort geht genau darum. Es kommt jedoch auf den vertraglichen Kontext und das Vertrauensniveau zwischen Anbieter und Kunde an. Man muss also daran erinnern, dass die Regel des Kunden König ist (in der Tat habe ich mehrmals mit Kunden erlebt, dass ich nach einer langen Debatte über die optimale Lösung diesen Satz aussprach und eine plötzliche Änderung der Einstellung und eine sorgfältige Überprüfung von Argumenten auslöste ;-) ).
Christophe
7
"Genauigkeitsproblem: Wenn Änderungen am Code vorgenommen werden, müssen diese in den Kommentaren vorgenommen werden, da sonst die Kommentare unbrauchbar werden." Ich würde sagen, es ist noch schlimmer als nur nutzlos . Ein Kommentar, der nicht mehr aktuell ist, kann sich schnell in einen Fehler verwandeln (oder von jemandem zurückgesetzt werden, weil er denkt, dass es sich um einen Fehler handelt), wenn Sie davon ausgehen, dass dies die Quelle der Wahrheit ist und Sie ihm vertrauen.
Hamatti
11
@ Hamatti In der Tat. Ich habe einmal eine beträchtliche Menge Zeit damit verbracht, die ursprüngliche Absicht hinter einer Zeile zu entziffern, die lautete:i++; // count down
TKK
18

Der Kunde möchte mindestens 25% der Kommentare in jedem seiner Softwareprojekte.

Möchte der Kunde wirklich 25% der Kommentare oder möchte Ihr Kunde, dass Ihr Code so aussagekräftig wie möglich ist?

IMHO weiß der Kunde, was er will, aber nicht, was er braucht. Da ein Kunde selbst kein Entwickler ist und Feedback von seinen eigenen Mitarbeitern / Kunden erhält, sieht Ihr Kunde nur den oberen Teil des Eisbergs.

Ich nehme an, Ihr Client hat einige Pseudokenntnisse und möchte, dass der Code gut dokumentiert und einfach und kostengünstig zu warten ist. Das Tool dafür sind Kommentare (in seinen Gedanken).

Versuchen Sie, mit ihm zu sprechen, und bereiten Sie einige Codefragmente mit gut geschriebenem Code vor, der sich selbst erklärt, und ein anderes schlecht geschriebenes mit Kommentaren. Nur ein paar Zeilen. Zeigen Sie dies bei Bedarf und verwenden Sie es als Bild für Ihre Worte.

Sprechen Sie mit Ihrem Kunden / Supervisor / was auch immer und versuchen Sie, ihm die modernen Prinzipien der Versionskontrolle (keine Notwendigkeit für Kommentare am Anfang der Datei) und des sauberen Codes (ich empfehle das Buch auch) und des sich daraus ergebenden selbsterklärenden Codes zu erklären.

Vielleicht können Sie und Ihr Team, wenn Sie es gut genug demonstrieren und Ihrem Kunden klar machen, dass er sauberen Code und nicht nur Kommentare will, besseren Code schreiben (mit viel weniger Kommentaren) und sofort zeigen, dass Sie einen guten Entwickler haben, den es sich zu behalten lohnt .

Chrᴉz
quelle
13
Selbsterklärender Code ist ein schönes Prinzip. Leider funktioniert es in der realen Welt nicht so gut. Schnittstellen und komplexe interne Abläufe müssen dokumentiert werden, und es reicht nicht aus, nur nette Namen zu wählen. Welche Einheiten sind diese Werte? Skalierungsfaktoren? Abtastraten? Wann ist es sicher, diese Methode aufzurufen, und wann nicht? Welche Ausnahmen werden für welche Bedingungen geworfen? Und so weiter und so fort. Dies macht Ihren Code wartbar. Die reale Welt hat eine Komplexität, die ein Code-Snippet niemals darstellen wird, und deshalb muss dies ordnungsgemäß dokumentiert werden.
Graham
2
@ Abraham Ja, Kommentare sind nicht ganz unvermeidlich. Kommentare sind jedoch wie Code: Je mehr Sie machen, desto mehr müssen gepflegt werden. Prägnant bleiben hilft mir zu glauben.
Robert Dundon
Ich möchte nicht sagen, dass einige Elemente völlig nutzlos sind, aber Kommentare genau wie der Name der Funktion oder der Variablen sind nicht nützlich. Das kurze Stück Code sollte zeigen, dass es ohne Kommentare möglich ist und keine kommentarfreie Umgebung erzwingen soll. Wenn Sie zeigen möchten, welche Ausnahmen ausgelöst werden, oder die Funktionsweise weiter beschreiben möchten, können Sie das Summary-Tag für Funktionen verwenden. Wenn Sie Abhängigkeiten signalisieren möchten, modellieren Sie das benötigte Objekt als Eingabeparameter usw. Es gibt keine perfekte Möglichkeit, alles zu tun. Holen Sie sich einfach das Beste aus beiden Welten
Chr --z
@ Chris Absolut, ich stimme zu. Wenn Kommentare keine Informationen hinzufügen, lassen Sie sie weg. Aber wie ich schon in einer anderen Antwort sagte, ist der Prozentsatz eigentlich nur ein Code-Geruchstest. Sie rechtfertigen es, der Auditor prüft es, alle machen weiter. Die Sorge ist jemand, der denkt, sein Code sei wirklich selbsterklärend und habe nicht über all diese Dinge nachgedacht.
Graham
12

Dies erinnert mich an die albernen Stapelüberlauf-Antworten, die Sie sehen und die aus einer Zeile bestehen, gefolgt von buchstäblich "etwas Text hier, um die minimale Zeichenbegrenzung zu erreichen".

In diesem Fall könnte argumentiert werden, dass zwei Personengruppen schuld sind:

  1. Die Menschen, die Grenzen setzen - das ist eindeutig übertrieben und verhindert, dass Menschen ihre richtig geformten Informationen übermitteln, ohne künstlichen Lärm hinzuzufügen

  2. Die Leute, die Informationen übermittelten, die nicht richtig geformt waren, fügten dann künstliches Rauschen hinzu, wenn das System sie aufforderte, stattdessen mehr tatsächliche Substanz hinzuzufügen

Manchmal ist eine Frage sowohl einfach als auch thematisch, und es gibt nicht viel mehr zu sagen als ein paar Worte. Dies ist jedoch äußerst selten. In fast allen Fällen gibt es viel mehr zu sagen. Wenn nichts anderes, sollte es offensichtlich sein, dass der Weg, um eine Zeichenbeschränkung zu umgehen, nicht darin besteht, einfach zufälliges Rauschen in Ihren Post zu werfen.

Diese Kommentarsituation, mit der Sie konfrontiert sind, ist fast dieselbe. Ihre Entwickler haben eine Anfrage nach Kommentaren angenommen und implementiert, indem sie zufälliges Rauschen in ihren Code eingefügt haben. Das Dokumentieren der Variablennamen direkt neben der Variablendeklaration ist Vandalismus . Das hätte niemals passieren dürfen.

"Aber wie sonst können wir zu 25% kommen?" Durch das Schreiben konkreter Sachäußerungen. Verwenden Sie mehr Worte, bessere Worte, die besten Worte, um die Wirkung von Funktionen zu dokumentieren. Erweitern Sie Ihre Erklärungen. Beschreiben Sie Randfälle ausführlicher.

Zurück zum ursprünglichen Punkt: Der Client ist auch hier teilweise schuld, weil "25% des Quellcodes" äußerst willkürlich ist. Letztendlich sind sie jedoch der Kunde, also machen Sie das Beste daraus. Aber ich meine "am besten". Nicht "das Schlimmste", wie es bisher passiert ist.

Leichtigkeitsrennen im Orbit
quelle
5

Ich weiß nicht, worum es bei dieser Anforderung geht.

Nur durch grundlegende Sauerstoffanreicherung Ihres Codes sind Sie wahrscheinlich schon bei 10% oder so. Nehmen wir noch einmal 5% der Kommentare, die Sie für sich selbst geschrieben haben (einige schreiben mehr, aber 5% scheinen eine konservative Schätzung zu sein, wenn Sie kein Schweigegelübde abgelegt haben). Zu diesem Zeitpunkt sind es ungefähr 15% (ja, ja, ich weiß, 5% von 90% sind weniger als 5%, nicht nitpicken). Wenn Ihr Sauerstoffgehalt weniger als 10% beträgt, sind Ihre Methoden möglicherweise sehr langwierig. In der Regel ist es eine gute Idee, sie in kleinere (meist private / geschützte) Klassen aufzuteilen oder allgemeinere Hilfsklassen usw. zu verwenden.

Für den Rest des Kommentartextes sollten Sie nun Entwurfsüberlegungen und Verwendungsszenarien in Kommentare auf Klassen- / Dateiebene einfügen. Haben Sie einige Tabellen oder ASCII-Kunst (oder Sauerstoff-Code, der schöner aussehende Sachen erzeugt, wenn es gerendert wird). Ich weiß natürlich nicht, worum es in Ihrem Projekt geht, aber ich glaube, Sie können dies ohne Dummy-Kommentare (mit Ausnahme der Doxygenation Boilerplate) tun und zu etwas in der Nähe von 25% kommen.

Wenn es nur 20% und nicht 25% sind - ich bin sicher, der Kunde hat diese Zahl nur willkürlich angegeben und wird damit einverstanden sein. Wie auch immer, sprechen Sie mit ihnen, um zu besprechen, was die Kommentare umfassen sollten. und zeige ihnen eine kommentierte Beispieldatei, um zu sehen, ob sie zufrieden sind. Wenn sie es sind, dann ist es das. Wenn sie denken, dass etwas fehlt, werden sie Ihnen sagen, was fehlt. Sie werden dir nicht sagen "Wir können keinen möglichen zusätzlichen Kommentar vorschlagen, aber wir möchten, dass du noch einen hinzufügst".

PS - Sehen Sie sich den Code der Standard-Java-Container an, um zu sehen, wie Sie ungefähr 70% erreichen können ...

einpoklum
quelle
5

25% -Kommentare in Ihrem Code zu haben, ist ein hervorragendes Ziel und macht den Kunden glücklich. Schreiben Sie jetzt 25% beschissene Füllerkommentare wie "i + = 1; // erhöhe i um 1". Nehmen Sie sich also Zeit, schreiben Sie nützliche Kommentare und genießen Sie das Gefühl, dass Sie tatsächlich dafür bezahlt werden, etwas zu tun, was Sie tun sollten sowieso.

gnasher729
quelle
Das ist auch schön +1. Ich weiß nicht, ob es ein gutes Ziel gibt, das in Bezug auf die Kommentarrate ausgedrückt wird, aber vielleicht erreichen viele von uns dieses '' Ziel '' auf nützliche Weise, ohne es zu wissen ... Ich habe kürzlich einen alten Code gefunden Das habe ich in den 80ern zu Beginn meiner Karriere mit einem innovativen Hochleistungsalgorithmus geschrieben: Er enthält nur 10% der Kommentare, aber im Nachhinein wünschte ich mir, ich hätte noch mehr darin ;-)
Christophe
4

Wir alle wissen, dass dies eine Mistanforderung ist. Die interessante Frage ist hier

Wie soll ich reagieren?

Ich glaube fest daran, Probleme sichtbar zu machen. Hier würde ich die Tatsache nutzen, dass Geld spricht.

Bitten Sie mich, dies zu tun, und ich sage, dass mein Gebot um 1% erhöht wird. Oh, aber es wird 20% zu zukünftigen Wartungsgeboten hinzufügen.

Nur einmal fragen sie, warum ich ihnen beibringe, dass der Sinn guter Namen darin besteht, die Notwendigkeit zu vermeiden, Kommentare abzugeben.

Als Alternative schlage ich vor, eine Dokumentation zu erstellen, die darauf abzielt, einen Wartungsprogrammierer mit einer definierten Anzahl von vorausgesetzten Qualifikationen zu befähigen, die Ideen hinter dem Projekt auf den neuesten Stand zu bringen. Oder sicher, ich könnte Ihnen 25% Kommentare geben. Wie du willst.

kandierte_orange
quelle
3

Ja, ich verstehe deine Frustration über die dumme Regel. Ich habe viele Programme mit sinnlosen Kommentaren wie gelesen

x = x + 1; // add 1 to x

Und ich sage mir, das ist was für ein Pluszeichen bedeutet !! Wow, danke, dass du es mir erzählt hast, das wusste ich nicht.

Aber das heißt, der Kunde bezahlt die Rechnung. Deshalb gibst du ihnen, was sie wollen. Wenn ich bei einem Autohaus arbeiten würde und ein Kunde sagte, er wolle einen Pickup, würde ich mich nicht mit ihm darüber streiten, ob er wirklich einen Pickup braucht, und ihn befragen, was er erwartet, damit anzufahren. Ich würde ihm einen Pickup verkaufen.

Okay, es gibt Zeiten, in denen das, was der Kunde wünscht und was er wirklich braucht, so weit voneinander entfernt ist, dass ich versuche, die Angelegenheit mit ihm zu besprechen, ihn vielleicht davon zu überzeugen, sich auf etwas Vernünftigeres zu einigen. Manchmal funktioniert das, manchmal nicht. Am Ende gebe ich ihm, was er will, wenn ich seine Meinung nicht ändern kann. Wenn er später wiederkommt und sagt: Oh, das hat meine geschäftlichen Anforderungen wirklich nicht erfüllt, können wir ihm mehr in Rechnung stellen, um das zu tun, was wir ihm beim ersten Mal gesagt haben. Wie viel Sie mit dem Kunden verhandeln können, hängt davon ab, wie sehr er Ihrem Fachwissen vertraut, wie der Vertrag mit Ihnen zur Organisation passt und ehrlich gesagt, wie eigenwillig er ist.

Es wäre ein sehr seltener Fall, in dem ich unter der Annahme, dass es an mir liegt, einen Vertrag verlieren würde, weil ich dachte, dass die Anforderungen schlecht konzipiert waren.

Denken Sie daran, dass die Personen, mit denen Ihr Unternehmen verhandelt, möglicherweise diejenigen sind, die diese 25% -Regel erfunden haben oder nicht. Es könnte eine Regel sein, die ihnen von oben auferlegt wird.

Ich sehe fünf mögliche Antworten:

Ein. Überzeugen Sie Ihren Chef oder jeden, der mit dem Kunden verhandelt, darüber zu streiten. Wahrscheinlich wird dies nichts bewirken, aber Sie können es versuchen.

Zwei. Weigere dich, es zu tun. Dadurch werden Sie wahrscheinlich entlassen, oder wenn das Unternehmen mit Ihnen einverstanden ist, verlieren Sie den Vertrag. Das scheint unproduktiv.

Drei. Schreiben Sie unbrauchbare Kommentare, um Platz zu schaffen, Kommentare, die nur wiederholen, was sich im Code befindet, und die jeder Programmierer, der den Code ändern kann, in 2 Sekunden sehen kann. Ich habe so viele Kommentare gesehen. Vor Jahren arbeitete ich für eine Firma, in der wir vor jeder Funktion, in der die Parameter aufgeführt sind, Kommentarblöcke einfügen mussten, wie z.

/*
GetFoo function
Parameters:
  name: String, contains name
  num: int, the number
  add_date: date, the date added
Returns:
  foo code: int
*/
int GetFoo(String name, int num, Date add_date)

Der Einwand, dass solche Kommentare eine Wartungslast darstellen, weil Sie sie auf dem neuesten Stand halten müssen, ist ungültig. Sie müssen nicht auf dem neuesten Stand gehalten werden, da kein seriöser Programmierer sie sich jemals ansehen wird. Wenn Sie diesbezüglich Fragen haben, sollten Sie allen Teammitgliedern klar machen, dass die nutzlosen, überflüssigen Kommentare ignoriert werden sollten. Wenn Sie wissen möchten, was die Parameter einer Funktion sind oder was eine Codezeile bewirkt, lesen Sie den Code, und sehen Sie sich die nutzlosen Kommentare nicht an.

Vier. Wenn Sie überflüssige wertlose Kommentare hinzufügen möchten, ist es möglicherweise die Zeit wert, ein Programm zu schreiben, um sie zu generieren. Etwas wie eine Investition im Vorfeld, könnte aber eine Menge Tipparbeit ersparen.

Als ich in diesem Geschäft anfing, verwendete eine Firma, für die ich arbeitete, ein Programm mit der Aufschrift "Schreibt Ihre Dokumentation für Sie! Vollständige Dokumentation für jedes Programm!" Das System verlangte, dass wir allen Variablen im Wesentlichen bedeutungslose Namen geben und dann eine Tabelle mit einem aussagekräftigen Namen für jede Variable erstellen. Die "automatische Dokumentation" ersetzte also im Wesentlichen den bedeutungslosen Namen, den wir verwenden mussten, durch einen aussagekräftigen Namen. Zum Beispiel - dies funktionierte mit COBOL - hätten Sie eine Zeile in Ihrem Programm, die besagt

MOVE IA010 TO WS124

und sie würden eine Reihe von "Dokumentationen" generieren, die besagten

COPY CUSTOMER NAME IN INPUT RECORD TO CUSTOMER-NAME IN WORKING STORAGE

Wie auch immer, man könnte mit Sicherheit ein Programm schreiben, mit dem man ziemlich leicht ebenso wertlose Dokumentation erstellen kann. Lesen Sie eine Zeile wie

a=b+c

und generiere den Kommentar

// add b to c and save result in a

Usw.

Fünf. Mach das Beste aus der dummen Regel. Versuchen Sie, nützliche und aussagekräftige Kommentare zu verfassen. Hey, es könnte eine gute Übung sein.

Oh, übrigens, darf ich hinzufügen, dass Sie die Metrik immer spielen können.

Ich erinnere mich, als ein Arbeitgeber sagte, sie würden damit beginnen, die Produktivität von Programmierern an der Anzahl der Codezeilen zu messen, die wir pro Woche erstellt haben. Als uns dies bei einem Treffen gesagt wurde, sagte ich: Großartig! Ich kann meine Punktzahl leicht steigern. Kein Schreiben mehr

x=x+4;

Stattdessen schreibe ich:

x=x+1;
x=x+1;
x=x+1;
x=x+1;

Schleifen? Vergiss es, ich werde den Code zehnmal kopieren und einfügen. Usw.

Wenn Sie also Kommentarzeilen zählen möchten, machen Sie jede Zeile kurz und setzen Sie die Idee in der nächsten Zeile fort. Wenn sich Änderungen in den Kommentaren ergeben, aktualisieren Sie den vorhandenen Kommentar nicht. Tragen Sie ein Datum ein, kopieren Sie den gesamten Text und schreiben Sie "Updated" und ein neues Datum. Wenn der Kunde Fragen stellt, teilen Sie ihm mit, dass Sie der Meinung sind, dass die Historie gepflegt werden muss. Usw.

Jay
quelle
2

Beliebige Metriken scheinen in zu vielen Projekten eine Tatsache zu sein ...

Dies zeigt sich häufig in dummen Anforderungen wie einer maximalen zyklomatischen Komplexität, die zu komplexerem Code führt, da Funktionen unnötigerweise aufgeteilt werden, um die Konformität zu gewährleisten, oder Dateien, die aufgeteilt werden, weil sie eine beliebige SLoC-Länge überschreiten

Kommentare sollten den Code ergänzen und erklären, was los ist (und nicht nur den Code wiederholen!).

Das heißt, wenn dies von Ihrem Kunden gewünscht wird und Ihr Unternehmen zugestimmt hat, zu liefern, stecken Sie fest, es sei denn, Ihr QA-Manager entwickelt eine Dosis gesunden Menschenverstands.

Andrew
quelle
Ja. Willkürliche Regeln führen dazu, dass Personen ihr Verhalten ändern, um die Regel zu nutzen. Das ist das Problem mit der Bürokratie. Es verblüfft mich, wie Leute eine Regel aufstellen können und nicht, dass die Leute, die von der Regel betroffen sind, dies berücksichtigen, wenn sie entscheiden, was zu tun ist. Dann machen sie mehr Regeln, um die Schlupflöcher zu stopfen, und mehr Regeln, um die Schlupflöcher zu stopfen, die durch die Schlupflöcher usw. erzeugt werden.
Jay
2

Kurzfristig gibt es nichts, was Sie wirklich tun können. Komm damit klar.

Sie sollten auch alle dummen Ideen ignorieren, die ich in diesem Thread über passive aggressive Proteste und alberne Witze im Code sehe.

Sobald Sie eine Vertrauensbeziehung mit dem Kunden aufgebaut haben, können diese Ihre Argumente besser anhören. Möglicherweise stellen Sie fest, dass dies eine dumme Forderung von einer Person ist, die einst Einfluss hatte, und dass sie intern nur sehr wenig Unterstützung hat.

Unter keinen Umständen sollten Sie ohne Erlaubnis des Kunden dagegen vorgehen.

gburton
quelle
2

Ich bin enttäuscht über die mangelnde Vorstellungskraft meiner Programmkollegen.

Mir scheint, der Kunde hat Nachforschungen angestellt. Möglicherweise hat er irgendwo gelesen, dass der Qualitätscode in der Regel etwa 25% der Kommentare enthält. Offensichtlich kümmert er sich weiter unten um die Instandhaltung. Wie konkretisiert er das in einem Anforderungsdokument, das an einen Vertrag gebunden werden soll? Das ist nicht einfach Es kann sogar unmöglich sein. Trotzdem möchte er sicherstellen, dass er ein gutes Preis-Leistungs-Verhältnis erhält, und zählt einige Qualitätsindikatoren auf.

Das klingt für mich überhaupt nicht dumm oder lächerlich. Die Leute, die die Anforderungen geschrieben haben, sind höchstwahrscheinlich keine Programmierer. Sie haben möglicherweise schlechte Erfahrungen mit einem früheren Projekt gemacht. Ihre Instandhalter beschweren sich: "Nichts von dieser Scheiße ist dokumentiert!". Es klingelt in den Ohren, als sie neue Anforderungen für das nächste Projekt schreiben.

Wenn Sie es ernst meinen, Ihren Code zu dokumentieren und den Kontext für die Wartungsgruppe bereitzustellen, wird diese Anforderung automatisch erfüllt. Sei also keine Pussy!

Am Ende, sei es 21% oder 29%, wird es niemanden interessieren. Der Kunde lässt Ihre Inhalte von einem unabhängigen Entwickler überprüfen und versteht besser, was Sie getan haben.

Martin Maat
quelle
1
Die Frage beweist definitiv, dass das Ausdrücken einer Kommentarquote als Ziel nach hinten losgeht. Es wäre für den Kunden effektiver gewesen, als Ziel Ziel zu haben, dass Code für einen anderen Entwickler verständlich sein muss (im Team? Von außen? Mit welchem ​​Hintergrundwissen und welchen Fähigkeiten?) Und die 25% als (flexible) Richtlinie anzugeben. Dies so auszudrücken, wäre für die Auftragnehmer verständlicher gewesen und hätte bessere Alternativen wie sauberen Code gefördert.
Christophe
0

Ich habe viele Programmierer getroffen, die nicht verstehen, wie es Menschen gibt, die derzeit nicht an diesem Projekt arbeiten.

Für sie ist alles, was sie wissen, allen bekannt.

Wenn jemand nicht ALLES weiß, was er gerade weiß, dann sind diese Leute für ihn "Idioten".

Mit diesem Standard können Sie Leute dazu zwingen, Kommentare zu schreiben.

Sie schreiben in 99% der Fälle unbrauchbare Kommentare, aber manchmal schreiben sie tatsächlich eines der Dinge auf, die "JEDER KENNT", und jemand, der neu im Team ist, verbringt möglicherweise nicht 16 Stunden damit, nach einem Fehler zu suchen (der bereits behoben wurde, aber dann wurde es aus einem anderen Grund rückgängig gemacht), was mit einem Kommentar an dieser Stelle im Code offensichtlich gewesen wäre.

Kommentare in Zeilen mit nicht offensichtlichen Fehlern können auch dazu beitragen, dass zukünftige Programmierer ein Programm nicht versehentlich vollständig abbrechen (insbesondere, wenn der Teil "Abgebrochen" bei einem schnellen Test nicht offensichtlich ist).

Hoffentlich hilfreich
quelle
3
Das Problem, 10000 Affen auf Schreibmaschinen schlagen zu lassen, ist nicht, dass sie nie etwas Wertvolles schreiben, sondern dass diese verschwundenen Edelsteine ​​im Müllhaufen schwer zu finden sind.
Deduplizierer