it-swarm.com.de

Mein Kunde möchte 25% der Kommentare in meinem aktuellen Projekt. Wie soll er reagieren?

junior Entwickler hier.

Ich arbeite derzeit 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 Anwendungen überprüft und hier sind meine Beobachtungen:

  • jede Datei beginnt mit einem Kommentarblock (Paket, Datum der letzten Aktualisierung, Name meines Unternehmens und Urheberrecht).
  • alle Variablen werden mit ihren Namen kommentiert // nameOfCustomer public String nameOfCustomer

  • alle Getter und Setter werden 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:

  • nutzlose 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?

97
Robin_

Alle anderen Antworten und Kommentare hier haben mich wirklich in eine Schleife geworfen, weil sie meiner ersten Reaktion und der Haltung, die ich bei meinen Kollegen gesehen habe, so widersprechen. Ich möchte also einen alternativen Ansatz beschreiben, schon allein, um die abweichende Stimme zu sein.

Das Leitprinzip dieser Antwort lautet: "Begeistern Sie den Kunden". Den Kunden zu begeistern bedeutet nicht nur, seine Erwartungen zu erfüllen. Es bedeutet, ihre Anfragen so tief zu verstehen, dass Sie das, was sie sagen, so interpretieren können, wie sie es meinen, und über das hinaus zu liefern, was sie verlangen. Andere Antworten scheinen sich stattdessen an dem Prinzip der böswilligen Einhaltung zu orientieren, das ich abscheulich finde. und außerdem ist fragwürdige Geschäftspraxis, da es ein schlechter Weg ist, Stammkunden zu gewinnen.

Wenn ich den Kunden sagen höre: "Ich möchte 25% Kommentare", ist dies für mich der Beginn eines Dialogs. Für mich ist klar, dass die Implikation hier "Ich möchte viel beschreibenden Text, damit Neulinge in dieser Codebasis schnell einsatzbereit sind" ist, nicht "Ich möchte, dass Sie Zufälligkeit in einer bestimmten syntaktischen Kategorie hinzufügen" als andere Antworten scheinen es zu nehmen. Und ich würde diese Anfrage ernst nehmen und beabsichtigen, viele beschreibende, hilfreiche Kommentare zu verfassen, einen Neuling in die Struktur des Codes zu führen, auf überraschende technische Entscheidungen hinzuweisen, die darin enthaltenen Überlegungen zu skizzieren und Englisch auf hohem Niveau zu geben Beschreibungen komplizierter Codeabschnitte (auch wenn sie keine Überraschungen enthalten). Diese Absicht und dieses Verständnis sind der Ausgangspunkt der Diskussion - das heißt, bevor wir überhaupt anfangen zu reden. Für mich ist die Implikation der Anfrage so klar, dass sie nicht einmal dieser Klarstellung bedarf. aber wenn es dir unklar ist, solltest du dich natürlich bei ihnen melden!

Okay, wohin geht der Dialog, wenn dies 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, bis dieser Prozess besprochen ist und warum es zusätzliche Arbeit ist, aber ich werde ihn hier weglassen, weil ich als professioneller Programmierer erwarte, dass Sie wissen wie schwer es ist gute Kommentare abgeben.
  2. "Ein ernsthafter zusätzlicher Aufwand" bedeutet, dass wir möglicherweise ein längeres Zeitbudget und ein größeres Geldbudget benötigen. oder Möglicherweise müssen wir das Funktionsbudget reduzieren. oder Möglicherweise müssen wir bei der Qualität und Quantität der Kommentare Kompromisse eingehen. Dieser Teil wird eine Art Verhandlung sein. Meiner Meinung nach sollten Sie jedoch die Kosten für diese zusätzliche Arbeit sehr genau kennen und sicherstellen, dass sie für den Kunden so wichtig sind, dass er bereit ist, diese Kosten zu übernehmen. Und wenn ja - großartig! Sie erhalten zusätzliche Zeit und Geld und sie erhalten qualitativ 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 zu verlieren, Widgets zu flurgeln, oder bereit sind, die Frist auf das späte Granuary 20x6 zu verschieben, dann gewinnt jeder erneut: Sie erhalten das Produkt, das sie haben wollen, und Sie müssen nicht den zusätzlichen Aufwand aufwenden, um qualitativ hochwertige Kommentare zu erstellen.

Hier sollte der Dialog meiner Meinung nach nicht gehen:

  1. Drohen Sie dem Kunden nicht mit Kommentaren von geringer Qualität. 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 die Zufälligkeit nach der Erstellung des Projekts automatisch generieren.
  2. Verstecke deine Pläne nicht. Versprich ihnen keine 25% Kommentare und dann automatisch Zufälligkeit, ohne ihnen zu sagen, dass du das tun wirst. Wann Sie bemerken (nicht wenn), dass Sie beide viel Zeit verlieren: Sie sind unzufrieden mit dem Produkt, das sie erhalten haben, und Sie erhalten negative Mundpropaganda.
  3. Versuchen Sie nicht, sie davon zu überzeugen, dass sie keine Kommentare wollen. Sie wollen eindeutig Kommentare. Diskutieren Sie Kompromisse zwischen verschiedenen Ansätzen: Ja! Besprechen Sie alternative Möglichkeiten, um den Codebase-Neuling freundlich zu machen: Ja! Sagen Sie ihnen, dass sie nicht wissen, was sie wollen: eh, nein. Sie möchten mit ihnen zusammenarbeiten, um ihnen das zu geben, was sie wollen. Verstehen Sie also, was das ist, und finden Sie heraus, wie Sie dies in einem von ihnen genehmigten Budget am besten erreichen können, und priorisieren Sie die Funktionen, die ihnen am wichtigsten sind, wenn die vorhandenen Ressourcen nicht ausreichen.
  4. Machen Sie keine Ausreden darüber, wie schwer es ist, Kommentare zu schreiben. Das Schreiben von Code ist schwierig. Das Debuggen von Code ist schwierig. Kommentare zu schreiben ist schwer. Wenn es einfach wäre, würden sie dich nicht einstellen. Überspringen Sie einfach die Beschwerden und kommen Sie direkt zu dem Punkt, der ihnen wichtig ist, nämlich wie sich der zusätzliche Aufwand auf sie auswirkt.
116
Daniel Wagner

Der Kunde ist König. Als Auftragnehmer müssen Sie also alles erfüllen, was der Kunde 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, andernfalls liegt eine Vertragsverletzung vor. Keine Wahl.

  • Formale Unternehmensqualitätsstandards: Selbst wenn es perfekt funktioniert, wird der Code, der nicht den Anforderungen entspricht, von so vielen Menschen als schlechte Qualität eingestuft, dass Sie alt sind, bevor Sie alle auf eine bessere Vorgehensweise umgestellt haben. Schlimmer noch: Bekannte Tools können verwendet werden, um solche Qualitätsmetriken zu automatisieren und zu legitimieren (z. B. Sonarwürfel ). Fast keine Wahl.

  • Ad-hoc-Kriterien, die von mehreren Personen beim Kunden definiert werden. Hier könnten Sie diskutieren. 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. Andernfalls werden die Kommentare möglicherweise unbrauchbar.
  • Refactoring-Problem: Da das Refactoring-Tool die Variablennamen in Kommentaren nicht verarbeitet.
  • Risikoproblem: Mehrdeutigkeit (oder Veralterung) von Kommentaren kann zu Verwirrung und Risiko führen, Fehler zu erhöhen.
  • Quantität ist keine Qualität
  • Diese lustige Sammlung nutzloser Kommentare zu StackOverflow .
  • Dieser Artikel das argumentiert, dass eine hohe Kommentarquote sogar das Zeichen eines Codegeruchs sein könnte.

Aber anstatt gegen das Schlechte zu sprechen und den Kunden zu konfrontieren, könnten Sie vielleicht einfach bessere Ansätze fördern:

  • Sauberer Code (schlagen Sie das Buch Ihrem Kunden vor: Es gibt einen überzeugenden Abschnitt, der Kommentaren und selbstdokumentierendem Code gewidmet ist).
  • Dokumentationspraxis: Die am schwierigsten zu erfassenden Dinge 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 anstatt in 1000 Kommentarwörtern?).

Wenn der Kunde immer noch nicht überzeugt ist, können Sie eine experimentelle Alternative vorschlagen. Mithilfe von Tools wird automatisch eine Dokumentation mit Kommentaren wie javadoc oder doxygen generiert. Schlagen Sie damit vor, den Fokus von Quantität (25% des Codes) auf Qualität zu verlagern (ein verständliches Javadoc zu generieren).

83
Christophe

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 denke, Ihr Kunde verfügt über Pseudo-Kenntnisse und möchte, dass Code gut dokumentiert und einfach und kostengünstig zu warten ist. Das Werkzeug hierfür sind Kommentare (in seinen Augen).

Versuchen Sie, mit ihm zu sprechen, und bereiten Sie einige Codefragmente mit gut geschriebenem Code vor, der sich selbst erklärt, und einen anderen schlecht geschriebenen 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/Vorgesetzten/was auch immer und versuchen Sie, ihm die modernen Prinzipien der Versionskontrolle (keine Kommentare am Anfang der Datei erforderlich) und des sauberen Codes (ich empfehle das Buch ) und zu erklären daraus resultierender selbsterklärender Code.

Wenn Sie es gut genug zeigen und Ihrem Kunden klar machen können, dass er sauberen Code und nicht nur Kommentare wünscht, können Sie und Ihr Team möglicherweise besseren Code (mit viel weniger Kommentaren) schreiben und sofort zeigen, dass Sie ein guter Entwickler sind, der es wert ist, behalten zu werden .

Dies erinnert mich an die albernen Stapelüberlauf-Antworten, die aus einer Zeile bestehen, gefolgt von "Text hier, um die minimale Zeichenbeschränkung zu erreichen".

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

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

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

Manchmal ist eine Frage sowohl einfach nd zum Thema, 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 Substanz zu sagen. Wenn nichts anderes, sollte es blendend offensichtlich sein, dass der Weg, um eine Zeichenbeschränkung zu umgehen, nicht darin besteht, zufälliges Rauschen in Ihren Beitrag zu werfen.

Diese Kommentarsituation ist fast dieselbe. Ihre Entwickler haben eine Anfrage nach Kommentaren entgegengenommen und diese implementiert, indem sie zufälliges Rauschen in ihren Code eingegeben haben. Die Dokumentation der Namen von Variablen direkt neben der Variablendeklaration lautet Vandalismus. Das hätte niemals passieren dürfen.

"Aber wie sonst können wir 25% erreichen?" Durch das Schreiben tatsächlicher Substanzkommentare. Verwenden Sie mehr Wörter, bessere Wörter, die besten Wörter, um die Wirkung von Funktionen zu dokumentieren. Erweitern Sie Ihre Erklärungen. Beschreiben Sie Edge-Fälle genauer.

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

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

Nur durch grundlegende Sauerstoffanreicherung Ihres Codes sind Sie wahrscheinlich bereits bei 10% oder so. Und nehmen wir noch 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 picken). Wenn Ihr Sauerstoffgehalt weniger als 10% beträgt, sind Ihre Methoden möglicherweise sehr lang. Es ist normalerweise eine gute Idee, sie in kleinere (meist private/geschützte) zu unterteilen oder allgemeinere Hilfsklassen usw. zu verwenden.

Fügen Sie nun für den Rest des Kommentartextes Entwurfsüberlegungen und Verwendungsszenarien in Kommentare auf Klassen-/Dateiebene ein. Haben Sie einige Tabellen oder ASCII-Grafik (oder Sauerstoffcode, der beim Rendern besser aussehende Inhalte generiert). Ich weiß natürlich nicht, worum es in Ihrem Projekt geht, aber ich glaube, Sie können dies ohne Dummy-Kommentare (außer dem Doxygenation Boilerplate) tun und zu etwas nahe 25% kommen.

Wenn es nur 20% und nicht 25% sind - ich bin sicher, der Kunde hat diese Zahl nur als etwas Willkürliches angegeben und wird damit einverstanden sein. Wie auch immer, sprechen Sie mit ihnen, um zu besprechen, was die Kommentare umfassen sollten. und zeigen Sie 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 Ihnen nicht sagen "Wir können keinen möglichen zusätzlichen Kommentar vorschlagen, aber wir möchten immer noch, dass Sie einige hinzufügen".

PS - Sehen Sie sich den Standardcode Java Container) an, um zu sehen, wie Sie 70% oder so erreichen können ...

5
einpoklum

25% Kommentare in Ihrem Code zu haben, ist ein ausgezeichnetes Ziel und macht den Kunden glücklich. Jetzt sollten Sie 25% beschissene Füllkommentare wie "i + = 1; // i um 1 erhöhen" schreiben. 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 wie auch immer.

5
gnasher729

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

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 werde sicher sagen, dass dies 1% zu meinem Gebot beiträgt. Oh, aber es werden 20% zu zukünftigen Wartungsangeboten hinzugefügt.

Nur wenn sie fragen, warum ich ihnen beibringe, dass es bei guten Namen darum geht, die Notwendigkeit von Kommentaren zu vermeiden.

Als Alternative schlage ich vor, eine Dokumentation zu erstellen, mit der ein Wartungsprogrammierer mit einem definierten Satz angenommener Qualifikationen über die Ideen hinter dem Projekt informiert werden soll. Oder sicher, ich könnte Ihnen 25% Kommentare geben. Wie du willst.

4
candied_orange

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

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

Und ich sage mir: DAS bedeutet also ein Pluszeichen !! Wow, danke, dass du es mir erzählt hast, das wusste ich nicht.

Der Kunde zahlt jedoch die Rechnung. Deshalb geben Sie ihnen, was sie wollen. Wenn ich bei einem Autohaus arbeiten würde und ein Kunde sagte, er wolle einen Pickup, würde ich nicht mit ihm darüber streiten, ob er wirklich einen Pickup braucht, und ihn fragen, was er erwartet, dass er ihn einholt. Ich würde ihm einen Pickup verkaufen.

Okay, es gibt Zeiten, in denen das, was der Kunde sagt, was er will und was er wirklich braucht, so weit voneinander entfernt ist, dass ich versuche, die Angelegenheit mit ihm zu besprechen und ihn vielleicht davon zu überzeugen, etwas Rationalerem zuzustimmen. Manchmal funktioniert das, manchmal nicht. Wenn ich seine Meinung nicht ändern kann, gebe ich ihm am Ende, was er will. Wenn er später zurückkommt 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 sein Vertrag mit Ihnen in die Organisation passt und wie offen gesagt er ist.

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

Denken Sie daran, dass die Personen, mit denen Ihr Unternehmen verhandelt, möglicherweise 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:

Eins. Überzeugen Sie Ihren Chef oder jeden, der mit dem Kunden verhandelt, darüber zu streiten. Die Chancen stehen gut, dass dies nichts bringt, aber Sie können es versuchen.

Zwei. Weigere dich, es zu tun. Dies wird Sie wahrscheinlich entlassen oder, wenn das Unternehmen Ihnen zustimmt, dazu führen, dass Sie den Vertrag verlieren. Dies scheint unproduktiv.

Drei. Schreiben Sie nutzlose Kommentare, um den Speicherplatz zu füllen. Diese Art von Kommentaren wiederholt nur den Inhalt des Codes und kann von jedem Programmierer, der den Code ändern kann, in 2 Sekunden angezeigt werden. Ich habe viele solche Kommentare gesehen. Vor Jahren arbeitete ich für eine Firma, in der wir vor jeder Funktion, in der die Parameter aufgelistet waren, Kommentarblöcke einfügen mussten, wie zum Beispiel:

/*
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 jemals ansehen wird. Wenn Sie Fragen dazu haben, stellen Sie allen Teammitgliedern klar, dass die nutzlosen, redundanten Kommentare ignoriert werden sollten. Wenn Sie wissen möchten, welche Parameter eine Funktion hat oder was eine Codezeile bewirkt, lesen Sie den Code und sehen Sie sich die nutzlosen Kommentare nicht an.

Vier. Wenn Sie redundante wertlose Kommentare hinzufügen möchten, lohnt es sich möglicherweise, ein Programm zu schreiben, um sie zu generieren. Eine Art Investition im Vorfeld, könnte aber eine Menge Tipparbeit sparen.

Als ich in diesem Geschäft anfing, verwendete eine Firma, für die ich arbeitete, ein Programm, das als "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 haben. Im Grunde genommen ersetzte die "automatische Dokumentation" 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

Auf jeden Fall könnte man sicher ein Programm schreiben, um ziemlich leicht ebenso wertlose Dokumentation zu generieren. Lesen Sie eine Zeile wie

a=b+c

und generieren Sie den Kommentar

// add b to c and save result in a

Usw.

Fünf. Machen Sie das Beste aus der dummen Regel. Versuchen Sie, nützliche und aussagekräftige Kommentare zu schreiben. 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, dass ein Arbeitgeber einmal sagte, er würde damit beginnen, die Produktivität von Programmierern daran zu messen, wie viele Codezeilen wir pro Woche produziert 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 hier Zeilen mit Kommentaren zählen möchten, machen Sie jede Zeile kurz und setzen Sie die Idee in der nächsten Zeile fort. Wenn sich an den Kommentaren etwas ändert, aktualisieren Sie den vorhandenen Kommentar nicht. Geben Sie ein Datum ein, kopieren Sie den gesamten Text und schreiben Sie "Aktualisiert" und ein neues Datum. Wenn der Kunde dies in Frage stellt, teilen Sie ihm mit, dass Sie es für erforderlich hielten, den Verlauf zu pflegen. Usw. usw.

3
Jay

Willkürliche Metriken scheinen in zu vielen Projekten eine Tatsache zu sein ...

Dies wird häufig in dummen Anforderungen wie einer maximalen zyklomatischen Komplexität gesehen, die zu komplexerem Code führt, weil Funktionen unnötig aufgeteilt werden, um die Konformität sicherzustellen, oder wenn Dateien 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 Ihr Kunde dies wünscht und Ihr Unternehmen zugestimmt hat, dies zu tun, stecken Sie fest, es sei denn, Ihr QS-Manager entwickelt eine Dosis gesunden Menschenverstand.

2
Andrew

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

Sie sollten auch all die 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 besser auf Ihre Argumentation hören. Möglicherweise stellen Sie fest, dass dies eine dumme Forderung einer Person ist, die einst Einfluss hatte, und dass sie intern nur sehr wenig Unterstützung hat.

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

2
gburton

Ich bin enttäuscht über den Mangel an Vorstellungskraft, den meine Programmierkollegen hier zeigen.

Es scheint mir, dass der Kunde einige Nachforschungen angestellt hat. Möglicherweise hat er irgendwo gelesen, dass der Qualitätscode normalerweise etwa 25% der Kommentare enthält. Offensichtlich kümmert er sich um die Wartung weiter unten. Wie konkretisiert er das in einem Anforderungsdokument, das an einen Vertrag gebunden werden soll? Das ist nicht einfach Es kann sogar unmöglich sein. Dennoch 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 Wartungsleute 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 Kontext für die Wartungsgruppe bereitzustellen, wird diese Anforderung automatisch erfüllt. Also sei keine Muschi!

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

2
Martin Maat

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

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

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

Mit diesem Standard können Sie die Leute dazu zwingen, sich daran zu gewöhnen, Kommentare zu schreiben.

Sie schreiben möglicherweise 99% der Zeit nutzlose Kommentare, aber manchmal schreiben sie tatsächlich eines der Dinge auf, die "JEDER WISST", und jemand, der neu im Team ist, verbringt möglicherweise nicht 16 Stunden damit, nach einem Fehler zu suchen (den jemand bereits behoben hat). wurde dann aber 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 unterbrechen (insbesondere, wenn der Teil "Unterbrochen sein" bei einem Schnelltest nicht offensichtlich ist).

0