it-swarm.dev

Mein Chef möchte eine zeilenweise englische Erklärung unseres Codes

Ich wurde ausdrücklich gebeten, zeilenweise (oder gegebenenfalls - zum Beispiel Bild für Bild usw.) Erklärungen oder Kommentare zu geben, die mein Chef lesen und befolgen möchte.

Da er kein Programmierer ist, kann er dem Code nicht folgen und möchte, dass alles ins Englische übersetzt wird.

Wurde schon einmal jemand darum gebeten?

Ich habe den gesamten Quellcode kommentiert und JSDoc verwendet, um eine vollständige Dokumentation aller Funktionen, Variablen usw. zu generieren. Dazu gehören ein Implementierungsbeispiel und vollständig funktionierende Demos mit Kommentaren.

Kann ich noch etwas tun, um den Code für Nicht-Programmierer zu kommentieren?

Dies ist keine vernünftige Anfrage, oder?


AKTUALISIEREN

Am Ende gelang es mir zu erklären, warum es keine gute Zeit war, das zu tun, was er verlangte. Er ist ein vernünftiger Typ und hatte einfach kein Verständnis dafür, was mein Job beinhaltet. Als er diesen Beitrag gesehen hat, hat er schnell verstanden, dass es keine normale Anfrage war.

Ich habe eine Dokumentation bereitgestellt, die für einen anderen Programmierer geeignet ist (JSDoc- und Inline-Kommentare - sowie einige zusätzliche Hinweise zu technischen Problemen), und ein sehr breites Flussdiagramm der Hauptlogik des Programms, dem mein Chef folgen kann.

Am Ende waren alle Parteien zufrieden und wir sind weitergegangen.

155
Billy Moon

Nein, es ist keine vernünftige Anfrage!

SPRECHEN SIE IHN AUS, oder lassen Sie ihn auf jeden Fall von jemand anderem ausreden. Das ist eine irrationale Idee, die zwar machbar ist, aber so teuer ist, dass sie eigentlich nie gemacht werden sollte. Eine Übersicht über Funktionen und Unterprogramme ist sinnvoll, aber nicht jede Codezeile zu "erklären". Es wäre für ihn effektiver zu lernen, die Sprache in der Hand zu lesen, als dies zu tun.

Als nächstes wird er darum bitten, mathematische Formeln oder so weiter in englischen Text zu übersetzen. Obwohl es durchaus möglich ist, dass führt viel Raum für Fehler und Fehlinterpretationen ein und sollte niemals getan werden. Genau wie das "Übersetzen" von Code ins Englische.

160
Rook

Haben Sie Designdokumente ? Dies ist die englische Erklärung dessen, was der Code tut. Ein Manager ohne Programmierung sollte nicht mehr benötigen.

150
Malfist

Gibt es eine Auszeichnung als Mikromanager des Jahres? Es hört sich so an, als hätte Ihr Chef eine Nominierung verdient. Jemand, der glaubt, dass er den Code Zeile für Zeile verstehen muss, aber nicht lernen möchte, wie man ihn direkt liest, ist so perfekt wie ein Mikromanager, wie man es sich vorstellen kann.

Ein Vorteil eines Entwicklers besteht darin, dass die Schwierigkeit, Code zu verstehen, ein Mikromanagement bis zu einem gewissen Grad verhindert, zumindest auf der detaillierten Implementierungsebene, zumindest durch nichttechnisches Management, da selbst der Hardcore-Mikromanager erkennt, dass dies der Fall ist über ihren Kopf auf dieser Ebene. Aber das Genie Ihres Chefs hat vielleicht einen Weg gefunden, den Silikonvorhang zu zerbrechen.

Und als Bonus verschwendet es enorm viel Entwicklerzeit für die Übersetzung, selbst vorher er verwendet die englische Übersetzung, um verschiedene Verbesserungen vorzuschlagen (ich gehe davon aus, dass er besser als die Programmierer programmieren kann , obwohl er den Code nicht lesen kann und seine Weisheit teilen kann, sobald jemand ihn übersetzt, sonst warum sollte er ihn brauchen jede Zeile übersetzt?).

Also, nein, es ist keine vernünftige Anfrage, und ich habe noch nie davon gehört. Und ich fühle für dich. Ich denke, jeder muss möglicherweise ruhig nach einem anderen Job suchen, denn sobald er die Codeübersetzung als Management-Tool einsetzt, wird es wahrscheinlich ein brutaler Arbeitsplatz (ähm, ein brutalerer Arbeitsplatz).

Auf der positiven Seite, vielleicht können Sie ein neues Anti-Muster bekommen, das nach Ihrer Situation benannt ist? Wie wäre es mit dem Anti-Pattern "Dirty Hungarian Phrasebook" nach dem Monty Python Sketch), bei dem ein Tabakhändler versucht, mit jemandem zu kommunizieren, der kein Englisch spricht, indem er einen ungarischen Sprachführer verwendet, der komisch ist falsche Übersetzungen?

113
psr

Setzen Sie sich zu ihm und sprechen Sie ihn durch 10 Zeilen des Codes. Erklären Sie jedes Detail, bis Sie beide zustimmen, dass er es so gut versteht, wie er es wollte.

Vielleicht ist diese Erfahrung alles, wonach er sucht: nur ein Eindruck davon, wie Ihre Arbeit für Sie aussieht und wie die Software aus Ihrer Sicht aussieht. Das ist eine gute Sache in meinem Buch.

Wenn er danach immer noch möchte, dass Sie fortfahren, sagen Sie: Beachten Sie, wie viele Fragen ich stellen musste; Stellen Sie sich vor, ich hätte das alles erklären müssen, ohne Fragen stellen zu können. Wie hätte ich möglicherweise wissen können, was ich einbeziehen und was ich weglassen sollte? Wie lange hätte es gedauert, bis die Ergebnisse für Sie nützlich wären? Wie viele Zeilen soll ich auf diese Weise machen?

91
reinierpost

Ich denke nicht, dass es eine vernünftige Bitte ist. SOURCE CODE ist nicht dazu gedacht, in Englisch (oder einer anderen Sprache) gelesen zu werden.

Vielleicht hat er Angst, dass Sie Ihren Code dazu bringen, etwas zu tun, das er nicht genehmigt oder dessen er sich bewusst ist. Wenn das der Fall ist, glaube ich nicht, dass Sie etwas dagegen tun können. Sie müssen die Dokumentation schreiben oder ihn/sie davon überzeugen, jemanden einzustellen, der Ihren Code prüft.

43

Es ist wirklich sehr einfach:

  • Sie wurden aufgrund Ihrer Fähigkeiten als Programmierer eingestellt
  • Ihr Manager verfügt nicht über diese Fähigkeiten
  • Ergo sollte Ihr Manager nicht vernünftigerweise erwarten, dass er vollständig verstehen kann, was Sie tun

Ich habe eine ähnliche Erfahrung wie in einem früheren Job gemacht. Mein Manager war ein Buchhalter (und daher sehr detailorientiert) und verstand die Programmierung nicht oder vertraute ihr nicht wirklich. Sie konnte nicht verstehen, dass sie als nicht-technische Person nicht erwarten sollte, die Details dessen, was ich schrieb, erfassen zu können. Nach vielen Anfragen nach übermäßiger Dokumentation und Anfragen, nicht-technische Benutzer in der Verwaltung und Änderung des Codes zu schulen (ja, wirklich), hörte ich auf, sie abzuspeisen, und lehnte dies sofort ab. Die Analogie, die ich erklärte, war einfach:

  • Ich bin kein Buchhalter
  • Ich sollte nicht erwarten, jede einzelne Transaktion oder Buchung in unseren Konten zu verstehen
  • Dies bedeutet nicht, dass die Konten falsch oder nicht vertrauenswürdig sind, nur weil ich sie nicht verstehe
  • Dies wird ermöglicht durch Vertrauen die Person, die sie zusammengestellt hat

Am Ende klingt das für mich so: ein Manager, der Schwierigkeiten hat, seinen Mitarbeitern zu vertrauen; oder befürchtet, dass sie gehen werden, und denkt, dass dies ein wirksamer Weg ist, um dagegen vorzugehen.

Die einzige Lösung besteht darin, sich hinzusetzen und zu erklären, warum dies keinen Sinn ergibt. Es ist Ihre Aufgabe, den Code zu verstehen und es jemandem mit ähnlichen Fähigkeiten wie Ihnen zu ermöglichen, ihn zu verstehen, nicht dem Ihres Managers. Es kann eine gute Idee sein, ihnen diesen Thread zu zeigen (oder eine wirklich, wirklich schreckliche, abhängig von ihrer Persönlichkeit).

32
John N

Zeile für Zeile ist lächerlich. Was ich vorschlagen könnte, ist das Angebot, Dokumente aus Kommentaren zu generieren und ihm das zu geben. Das war ausreichend für eine Reihe von Zuschüssen und Audits der kanadischen Regierung, an denen ich in der Vergangenheit gearbeitet habe.

Er wird nicht Zeile für Zeile erhalten, aber er wird Methode für Methode erhalten, die immer noch granularer sein sollte, als er benötigt.

Einige vorhandene Lösungen, abhängig von Ihrer Plattform:

  • C #: Sandburg
  • Java: javadoc
  • "C++, C, Java, Objective-C, Python, IDL (Corba- und Microsoft-Varianten), Fortran, VHDL, PHP, C # und bis zu einem gewissen Grad D." : Sauerstoff
25
Steven Evers

Es wäre für ihn viel schneller, das Lesen von Code zu lernen, als den gesamten Code einer interessanten Anwendung ins Englische zu übersetzen. Außerdem haben wir das mit COBOL versucht und es hat überhaupt nicht geholfen. Wenn er nicht bereit ist zu lernen, sondern nur seine Unwissenheit zum Problem eines anderen machen will, haben Sie einen ernsthaft spitzen Chef.

16
kevin cline

Verwenden Sie Ihr technisches Fachwissen, um Ihren Chef zu verfolgen.

  1. Lassen Sie ihn wissen, dass dies genauso lange dauern wird wie das erstmalige Codieren (Sie können es gerne verlängern).
  2. Fragen Sie ihn, wie aktuell dieses Dokument sein muss. Informieren Sie ihn, dass alle Codierungsänderungen jetzt mindestens doppelt so lange dauern.
  3. Wenn Sie oder jemand anderes Fehler findet, fragen Sie ihn, ob Sie diese jetzt beheben sollten, oder warten Sie, bis Sie mit der Pseudo-Codierung fertig sind. Erinnern Sie ihn an # 1 & # 2.

Wie bei allen schlechten Lösungsvorschlägen ist es besser, das Problem zu identifizieren. Vielleicht wird Ihr Chef vom oberen Management mit technischen Fragen konfrontiert und es ist ihm peinlich, da er nicht antworten kann. Es könnte einen bestimmten Codeabschnitt geben, über den er sich am meisten Sorgen macht, sodass Sie dieses massive Unterfangen auf genau diesen Bereich beschränken können.

Wenn Sie ein Beispiel einreichen, kann er zu dem Schluss kommen, dass es keine Rolle spielt, in welcher Sprache es sich befindet, wenn Sie nicht verstehen, wie das Codieren funktioniert (Was ist eine Schleife und was macht es mit all diesen Elementen?) das Verständnis der Anwendung aus der Perspektive eines Power-Users. Ich denke, es ist fair für Sie, ihn wissen zu lassen, dass Sie lieber echten Code/Hinweis schreiben möchten - ich suche einen anderen Job.

15
JeffO

Warum?

Ein zeilenweiser Kommentar ist nicht sinnvoll, aber ich würde Folgendes fragen: warum willst du das?

Ist es weil...

  • sie möchten ein umfassendes Verständnis dafür haben, was die Software tut (nicht unbedingt wie)?
  • sie möchten sicher sein, dass ein anderer Programmierer das Projekt abholen kann, wenn ich gehe?
  • sie wollen sehen, dass ich echte Arbeit mache?

Möglicherweise steckt hinter dieser Anfrage ein vernünftiger Wunsch, und Sie können Ihren Chef möglicherweise glücklich machen, indem Sie dies herausfinden und diesen Bedarf decken.

Aktualisieren

Beyogen auf Mikey's Kommentar, vielleicht habe ich das etwas zu unverblümt gesagt. Ich meine nicht, dass du wörtlich sagen solltest "warum willst du das?", Nur das das solltest du herausfinden. Wortlaut und Tonfall machen einen großen Unterschied. Konkret könnte man so etwas sagen wie:

"Ich habe über Ihre Bitte nachgedacht, eine Erklärung für jede einzelne Codezeile zu erhalten. Es ist ein bisschen ungewöhnlich, Dinge so zu machen. Ich habe mich gefragt, ob ich Ihnen vielleicht etwas nicht gut über meine Arbeit mitteilen kann. Was möchten Sie wirklich über unseren Code verstehen oder was ich tue? Was versuchen Sie hier zu erreichen? "

Natürlich ist es möglich, dass Ihr Chef völlig unvernünftig ist. Aber es ist wahrscheinlicher, dass er nicht weiß, wie ausgefallen diese Bitte ist und ein rationales Ziel vor Augen hat.

Wenn nicht, beginnen Sie mit dem Polieren Ihres Lebenslaufs. :) :)

12
Nathan Long

Selbst eine zeilenweise Übersetzung vermittelt nicht effektiv die Bedeutung jeder Codezeile. Das Verständnis eines Programmierers für eine Codezeile steht immer im Zusammenhang mit vielen Faktoren. Wenn Sie sich auf so etwas wie einen Multithread-Code einlassen, ist die englische Übersetzung nicht sinnvoller als der Rohcode. Denken Sie an Funktionen, die auf mehrere Funktionen/Dateien verteilt sind. Einige Codes machen absolut keinen Sinn, ohne umfangreiche Mengen anderen Codes zu erklären. Versuchen Sie, die verschiedenen Teile der Abhängigkeitsinjektion "Zeile für Zeile" zu erklären, und Sie werden sehen, was ich meine. Fast alles, was über den prozeduralen Code der Gottfunktion hinausgeht, erfordert ein umfangreiches Programmierwissen, um die englische Übersetzung zu verstehen. Schauen Sie sich auch etwas so Einfaches wie eine if/else-Entscheidungserklärung an. Es gibt keine Zeile für Zeile, da die nächste Zeile von Laufzeitdaten abhängig ist. Die nächste Zeile könnte eine von mehreren Möglichkeiten sein. Wenn Sie erklärt haben, was Ihre Anwendung tut, haben Sie Ihre PM zu einem Programmierer gemacht und Sie werden beide 5 Jahre älter sein.

10

Da ich früher Programmieren unterrichtete, würde ich es gerne ausprobieren.

Er wird schnell herausfinden, dass er mehr bekommt, als er erwartet hatte, was mich traurig machen wird, weil ich wie Dinge erkläre : -)

10
Mike Dunlavey

Wenn Sie sich auf Ihren "Chef" beziehen, ist dies "ein mittlerer Manager, der für Sie/Ihr Team verantwortlich ist"? oder der Eigentümer Ihres Unternehmens? Werden Sie "stundenweise" oder "auf Gehalt" bezahlt?

WENN Ihr Chef ein verantwortlicher Manager der mittleren Ebene ist, SPRECHEN SIE MIT SEINEM BOSS. Weisen Sie darauf hin, dass Ihre Produktivität für das Unternehmen auf 1/3 der möglichen Produktivität reduziert wird, um die Anforderungen Ihres Chefs zu erfüllen.

WENN Ihr Chef "der Typ ist, der die Schecks unterschreibt", erklären Sie ihm dasselbe, nur diplomatischer. Ihr Job ist von "Code schreiben" zu "Code schreiben, Erklärung des Codes schreiben, Erklärung erklären" übergegangen.

enter image description here

10
Cos Callis

Klingt nach einer guten Gelegenheit, die Programmierung zu beherrschen. Google es. :) :)

Aber ... es ist nicht unbedingt eine völlig unvernünftige Anfrage. Ein Teil Ihrer Aufgabe (der wichtigere Teil, imo) besteht darin, Ihre Algorithmen anderen Entwicklern und gegebenenfalls nicht technischen Personen mitzuteilen. Einsame geniale Programmierer, die nicht kommunizieren können, sind immer problematisch, denke ich.

Zu diesem Zweck sollte Ihr Code verdammt klar sein (was bedeutet: entweder wirklich selbstdokumentierend oder gut dokumentiert, und mit "selbstdokumentierend" meine ich, dass Variablen und Funktionen eine Bedeutung oder Verantwortung haben und ihre Namen widerspiegeln das klar). Ihr Chef kann gute Gründe für seine Anfrage haben. Vielleicht (ich vermute hier nur) Sie oder Ihr Vorgänger haben den Ruf, undurchdringlichen, fragilen Code zu haben, und dies ist das Mittel Ihres Chefs. Es ist ein bisschen extrem, könnte aber eine nützliche Übung für Sie sein. Ich nehme an, er weiß, dass es Zeit braucht, um bessere Dokumente zu schreiben (und wenn er es nicht tut, sollte er ausgebildet werden - es ist wie beim Schreiben einer Hausarbeit: Das Schreiben dauert länger als das Lesen).

10
JohnL4

Ein Flussdiagramm wird ihm wahrscheinlich von größerem Nutzen sein. Dies ist sicherlich eine ungewöhnliche Anfrage und sagt nicht viel über ihn als Manager aus.

9
James

Die Tatsache, dass Ihr Chef bereit ist, einige Zeit damit zu verbringen, den von Ihnen geschriebenen Code zu verstehen, könnten Sie zu Ihrem Vorteil nutzen. Versuchen Sie, ihn mit Cucumber bekannt zu machen: http://cukes.info/

und lassen Sie Ihren Chef in Zukunft einen BDD-Test für Sie schreiben.

8
moonflash

Das Schöne am Englischen ist, dass es wunderschön verdeckt ist. Wenn Sie dies zu Ihrem Vorteil nutzen, müssen Sie diese Art von Anfrage möglicherweise nie wieder bearbeiten. Ich würde ein kleines Stück des Codes als Beispiel nehmen, aber eines, das sehr abstrahiert und überhaupt nicht leicht zu verstehen ist. Ich würde dann die Kommentare in technischem Englisch schreiben, als ob Sie sie für ein Kapitel in einem Programmierbuch schreiben würden. Je länger und komplizierter es ist, desto besser. Sagen Sie ihm, wie viele Stunden Sie gebraucht haben, um diese eine Funktion zu dokumentieren. Erklären Sie dann, dass es nur 1/10 von 1% (verwenden Sie tatsächliche Zahlen basierend auf Codezeilen, wenn Sie können, sie sind wahrscheinlich schlechter als diese) der tatsächlichen Codebasis ist. Wenn er merkt, dass er keine Ahnung hat, was die englische Übersetzung sagt, und dass es 20.000 Mannstunden dauern wird, um diese Dokumentationsstufe zu erreichen, wird er sich ziemlich schnell zurückziehen. Aber sei sehr ernsthaft bemüht, seine Aufgabe zu erfüllen. Versuchen Sie das nicht, wenn Sie das nicht schaffen und er vermutet, dass Sie ihn spielen.

6
HLGEM

Dies sieht aus wie ein Kandidat für eine spezielle Urlaubsausgabe, spitzer Chef Dilbert Streifen! Seine Bitte klingt auf den ersten Blick sicherlich nicht vernünftig .

Abgesehen von Humor, versuchen Sie herauszufinden, was er wirklich braucht und warum, und teilen Sie ihm dann mit, was es in Dollar oder Stunden kosten wird, ihm das zu geben. und lassen Sie ihn entscheiden, ob er so viel Geld dafür ausgeben möchte.

Zählen Sie die Stunden auf, die Sie benötigen, um seine scheinbar bizarre Anfrage zu erfüllen, und stellen Sie dann fest, ob es nicht besser ist, einen Bruchteil dieser Zeit in die Suche nach einem neuen Arbeitsplatz für einen Arbeitgeber zu investieren, der bereit ist, Sie zu behandeln als Profi!

6
John Tobler

Bringen Sie ihn in Ihr Büro und geben Sie ihm einen Rundgang durch Ihren Code.

Er wird auf halbem Weg erkennen, dass er eine absurde Forderung gestellt hat, und er wird weggehen und dich nie wieder stören.

Wenn Sie seinen Forderungen nicht nachgeben, um ihm zu helfen, Ihren Code zu verstehen, wird er verschiedene, aber ebenso absurde Wege finden, Sie anzustupsen.

Dies ist ein Fall, in dem Appeasement besser funktioniert als Abrieb.

6
Rei Miyasaka

Es wäre sehr schön, wenn wir einen Übersetzer "Language X to English" hätten, der dies tut. Dann könnte man grinsen und sagen, kein Problem, Boss, das haben Sie in einer Minute. Und dann kommt eine Mail mit einigen Megabyte Text, die lautet:

  • Sei a ein neues Integer-Array mit 20 Elementen.
  • Sei x eine Variable zum Speichern von ganzen Zahlen.
  • Setze x auf 0
  • Während x kleiner als 20 ist, tun Sie, was in den nächsten 2 Zeilen vorgeschrieben ist
  • setzen Sie das Array-Element von a mit dem Index x auf das Ergebnis des Aufrufs von nThPrime mit dem Argument x + 1
  • x um 1 erhöhen
  • ....

Eine andere Möglichkeit wäre, fortan die Programmierung in Shakespeare vorzuschlagen.

6
Ingo

Er sollte sich nicht die Mühe machen, etwas davon zu wissen. Sagen Sie ihm, dass sich die Implementierung in der Softwareentwicklung ändern kann. Das Eventdesign kann sich ändern. Erzählen Sie ihm von Informationen, die sich verstecken, einkapseln und abstrahieren.
Er sollte als Teil Ihres Teams, als Client Ihres Codes im weiteren Sinne, nur mit einer klaren Abstraktion auf hoher Ebene arbeiten, was Ihr Code tut. Auf die gleiche Weise funktioniert jede Ebene Ihres Codes mit einer anderen Ebene des Codes einer anderen Person. Wenn Sie mehr wissen, wird er nur langsamer und riskiert, dass er Annahmen trifft, die auf dem Innenleben Ihres Codes basieren. Diese Annahmen werden nicht mehr gelten, wenn Sie Ihren Code ändern müssen, was zu einem Problem wird, wenn er ein System oder einen Prozess darauf aufbaut.
Und auch diese Art von Arbeit zu erledigen, verringert Ihre Effizienz. Sie müssen nicht nur nachfolgende Änderungen an zwei verschiedenen Stellen vornehmen, sondern dies wirkt sich auch negativ auf Ihre Arbeitsmoral aus, wodurch sich Ihre Leistung noch weiter verringert.

6
back2dos

Mein Chef möchte eine zeilenweise englische Erklärung unseres Codes

Zäh.

Da er kein Programmierer ist, kann er dem Code nicht folgen und möchte, dass alles ins Englische übersetzt wird.

Wenn er kein Programmierer ist, sollte er den Code nicht lesen. überhaupt

Stellen Sie stattdessen eine allgemeine Dokumentation bereit.

Dies ist keine vernünftige Anfrage, oder?

Nein.

Wahrscheinlich ist diese Anfrage ein guter Zeitpunkt, um Dinge wie ANTLR zu lernen. Nehmen Sie ANTLR, nehmen Sie die Grammatik Ihrer Sprache, analysieren Sie den gesamten Code, den Sie haben, durchlaufen Sie Ihre AST und generieren Sie vorlagenbasierte Beschreibungen für jeden Knoten, also i++ wird beschrieben als increase i by 1 using postfix increment operator. Das sollte wirklich lustig sein. Ihr Chef möchte möglicherweise auch, dass dieses Tool in das Build-Skript aufgenommen wird. Jedes Mal, wenn Sie Änderungen vornehmen, erhält er eine E-Mail mit ca. 20 MB, in der beschrieben wird, was die neue Version tut.

P.S. Nur ein Scherz, er ist ein Idiot.

4
Andrey Agibalov

Als Programmierer haben Sie wirklich "zwei" Jobs.

Das erste ist, gute Programme zu erstellen. Die zweite besteht darin, sie an Kunden innerhalb und außerhalb des Unternehmens zu "verkaufen".

Die Anfrage Ihres Chefs "verletzt" Ihren ersten Job. Die Dokumentation Ihrer Programme dauert länger. Auf der anderen Seite bringt er Sie dazu, bei Ihrem "zweiten" Job härter zu arbeiten.

Ihr Chef bittet Sie, Ihr Programm auf Englisch zu dokumentieren, um SEINEN Nutzen zu erzielen, und vermutlich zum Nutzen der Menschen, mit denen er innerhalb und außerhalb des Unternehmens zu tun hat. Wenn Sie ihm bei seiner Arbeit helfen, sollte dies langfristig zu Ihrem Vorteil sein, wenn Sie ihn um mehr Hardware, Personal oder Geld für Erhöhungen bitten. Immerhin hat er Sie gebeten, mehr zu arbeiten.

4
Tom Au

Ich denke, BDD würde gut zu diesem Problem passen, obwohl es so aussieht, als ob Ihr Projekt kurz vor dem Abschluss steht. Es ist also ziemlich schwierig, es jetzt zu implementieren, also ist es mehr wie zum späteren Nachschlagen.

Bei BDD werden Anwendungsfälle als für Menschen lesbare Dokumente beschrieben, die dann in automatisierte Funktionstests übersetzt werden.

4
Inoryy

Sie könnten einige Abnahmetests mit einem verhaltensgesteuerten Design-Framework wie Gurke schreiben. Das erklärt den Code nicht. es wird erklären, was es tut, und zwar in natürlicher Sprache. Es hat auch den Vorteil, dass es ausführbar ist, sodass Sie immer sicher sein können, dass die Dokumentation auf dem neuesten Stand ist. Andernfalls ist der Testläufer rot.

Schauen Sie sich das Intro-Video an. Vielleicht ist es eine gute Abwechslung, wenn Sie einen neuen Chef finden ... ;-)

3
Peter Mounce

Obwohl ich damit einverstanden bin, dass dies eine unvernünftige Anfrage ist, kann Ihr Chef etwas wie die Ausgabe von Docco schätzen, die Ihren Code und zeilenweise oder klauselweise Kommentare in zweispaltiges HTML trennt Ausgabe mit dem Code auf der einen Seite und der Prosa auf der anderen Seite. Sie müssen die Kommentare natürlich selbst eingeben, aber die Präsentation ist meiner Meinung nach ziemlich nett, auch für nicht-technische Leser. Siehe zum Beispiel ein zeilenweise kommentierter Abschnitt des kommentierten Codes für Underscore.js . Es gibt auch Python und Shell-Skriptversionen.

3
btown

Es ist möglich, dass Ihr Chef nur uninformiert und eingeschüchtert ist, aber tatsächlich eine vernünftige Person. Wenn ja, könnte das Denken mit ihm/ihr funktionieren - ein ungezwungenes Gespräch, bei dem Sie versprechen, "das zu liefern, was er wirklich will", dh; eine Prosa-Anleitung, was das Programm tut.

Wenn es um "meinen Weg oder die Autobahn" geht, überprüfen Sie jetzt besser Ihr Benzin.

3
ddyer

Ihr Manager ist mit ziemlicher Sicherheit beunruhigt darüber, dass er nicht versteht, was die von ihm verwalteten Mitarbeiter tun, und dass er nicht über den Hintergrund verfügt, um die von ihnen erzielten Ergebnisse zu verstehen.

Ich bezweifle, dass er diese Lösung sehr gründlich durchdacht hat, und es schien ihm auf den ersten Blick wahrscheinlich vernünftig. Aber das liegt hauptsächlich daran, dass er nicht versteht, was Programmiercode eigentlich ist.

Jeder Programmierer versteht die Absurdität dieser Anfrage, aber wir tun dies, weil wir intuitiv wissen, dass, sobald Sie die Sprache überwunden haben, nur noch der Algorithmus offenbart wird, der ebenso kryptisch ist.

// Set s to the first address in the server list
server_info *s = cmd->servers;
// Loop until s is NULL
while (s) {
    // call the server's init function passing our current ID and address
    s->init(proc->id,*addr);
    // call log::info with our custom message
    log::info("Starting server %s",s->name);
    // Set s to the value returned by the server's next() function
    s=s->next();
} // end of loop

Das Problem hierbei ist, dass Sie in den Kommentaren zwar erklären, was jede Zeile tut, Sie jedoch keine Ahnung haben, was der Code wirklich tut, es sei denn, Sie verstehen alle Auswirkungen. Es ist offensichtlich, wenn Sie ein Programmierer sind und dieses Muster schon einmal gesehen haben. Aber zeigen Sie dies jemandem, der nur den Verkauf versteht, und er wird nach dem Lesen der Kommentare genauso verwirrt sein wie zuvor.

Sie könnten tatsächlich Zeit sparen, indem Sie Ihrem Chef einige grundlegende Programmieraufgaben beibringen. Wenn er Ihren Code lesen möchte, geben Sie ihm die Werkzeuge, um dies zu tun. Die meisten Sprachen sind syntaktisch ziemlich kompakt, und das Erlernen der Struktur dauert nur ein oder zwei Stunden. Er wird mit ziemlicher Sicherheit nach ein paar Tagen aufgeben, aber zumindest wird er wissen, was er weitergibt, und was noch wichtiger ist warum er möchte Ihren Code nicht lesen.

2
tylerl

Fragen Sie sie, warum oder was ihre Motivation für die Anfrage ist, und bestimmen Sie dann ehrlich die damit verbundenen Kosten und teilen Sie sie dem Antragsteller mit. Wenn dies eine unvernünftige und möglicherweise böswillige Anfrage ist, suchen Sie einen anderen Job.

1
Iggy

Fragen Sie zunächst, was das Ziel hier ist. Überlegen Sie sich alternative Wege, um die Erklärung zu finden, die er hat.

Geben Sie als Nächstes eine Schätzung an, wie lange dies dauern würde, sowohl in Bezug auf die Anzahl der Stunden, die für die Zusammenstellung benötigt werden, als auch in Bezug auf die Dauer, die für die Durchführung benötigt wird. Fragen Sie in fein formulierten Worten, ob Ihre Zeit nicht besser damit verbracht wird, etwas anderes zu tun.

Sagen Sie ihm zunächst, wie viele tausend Codezeilen Ihre App enthält.

Wenn dies fehlschlägt, wie bereits vorgeschlagen, geben Sie ein Beispiel dafür, was er erwarten sollte, wenn Sie den gesamten Code mit ihm erzählen. Das sollte ihn befriedigen.

Wenn er weiterhin besteht, suchen Sie sich nach einem neuen Job.

Übrigens ist dies wirklich ein Fall, in dem der Projektmanager eingreifen und dem Chef erklären sollte, dass dieser Detaillierungsgrad nicht im Interesse aller liegt.

1
Joost Schuur

Dies ist keine irrationale Idee und durchaus logisch. Es ist ihre Pflicht, den Code zu überprüfen und festzustellen, ob etwas zu brechen ist.

Jetzt liegt es an Ihnen, was Sie tun können, um es einfach zu machen. Wie bereits erwähnt, kann die Erstellung eines guten Entwurfsdokuments mit einfachen UML-Diagrammen der beste Weg sein. Es ist nicht immer notwendig, zeilenweise zu kommentieren. Als Endbenutzer (oder Kunde) kann jemand eine Anfrage stellen. Jetzt liegt es an Ihnen, wie Sie diese vollständig ausfüllen (Erstellen von Design- oder Endbenutzerdokumenten oder zeilenweises Schreiben von Kommentaren).

Selbst in meinem Job, als ich in eine neue Firma eintrat, wurde ich von meinem Lead dazu aufgefordert. Wenn Sie an einem Ort neu sind, brauchen Sie einige Zeit, um Ihren Ruf aufzubauen, und zu diesem Zeitpunkt kommen solche Anfragen. Ich habe es erfüllt, indem ich UML Diagramme modulweise erstellt habe.

1
developer123

Eine zeilenweise Erklärung erhöht definitiv die Größe Ihrer Codierungsdatei. Dies ist der Grund für die separate Einführung der Dokumentation.

Wenn er zeilenweise viel detaillierter erklären möchte, fügen Sie einfach die Dokumentation der Programmiersprache bei, in der Sie codiert haben, und bitten Sie ihn, darauf zu verweisen (z. B. wenn Sie in Java verweisen dann auf JavaTM 2 Platform, Standard Edition, v 1.4.2 API-Spezifikation).
Auf jeden Fall wird dies funktionieren. :-)

1
Dinesh Kumar

Code IST Englisch bereits, 'für', 'wenn', 'sonst' usw. Führen Sie einfach eine Suche durch und ersetzen Sie sie nach bestimmten Zeichen. Ersetzen Sie beispielsweise '>' durch 'größer als'.

1
Sam

"Sicher kein Problem"

Beginnen Sie in Zeile eins Ihrer JavaScript-Anwendung <!DOCTYPE html>

Und einen Drilldown bis zur CPU-Elektronik ...

Tun Sie dies für jedes Codebyte.

Erklären Sie, was Doctype ist, erklären Sie den Vorschlag, erklären Sie die Geschichte, erklären Sie die Alternativen.

Problem?

1
Incognito

IMHO ... wenn er für die Erledigung der Aufgabe verantwortlich ist, sollte er wissen, wie es funktioniert ... :)

1
John K.

Ich würde nur sagen, dass Sie mehr als der Wille sind, es zu tun, aber es wird x Wochen dauern, bis Sie fertig sind, und ist er sicher, dass er will/braucht, dass Sie es tun?

Sicher wird er erkennen, dass Sie Ihre Zeit besser woanders verbringen würden?

1
Yeodave

Ich erstelle "auf Englisch" Erklärungen für fast jede andere Zeile meines Codes - in den Codekommentaren. Ich sehe das nicht als unzumutbare Belastung. Sicherlich, wie Sie es beschreiben, scheint es ein bisschen faul zu sein. Alles andere ist eine rote Fahne, dass Sie möglicherweise einen unvernünftigen Chef haben oder ein Problem mit Ihrer Arbeitsbeziehung vorliegt.

0
whitehawk

Wir hatten alle irgendwann Manager, die so etwas Lächerliches wollen. Es ist schwer, nicht halb gespannt davonzukommen, aber es ist wichtig, dass Sie es nicht tun - er wird sich nur einarbeiten. Vielleicht können Sie ihm eine Liste mit Vor- und Nachteilen erstellen und sie mit ihm durchgehen. Meiner Meinung nach ist der erste Punkt auf der Gegenseite, dass guter Code selbstdokumentierend ist. Aber darauf fallen sie kaum herein.

0
Dave

Dies mag eine dumme Sache sein, tatsächlich zu tun, aber könnten Sie einen Compiler zusammenstellen, der alle Sprachen, die Sie verwenden, in englische "Prosa" kompiliert? Sie können Ihren Code durch den Compiler ausführen, mithilfe von wc herausfinden, wie viele Zeilen er enthält, und ihn dann Ihrem Chef zur Verfügung stellen (möglicherweise drohen, ihn zu drucken;).

0
compman

Ich würde sagen, wenn ich ihm diese Frage und alle Antworten, die Sie haben, zeige, würde er verstehen, dass er unvernünftig ist! Versuchen Sie also, ihn zu bitten, alle Antworten hier zu sehen, aber natürlich auf nicht anstößige und respektvolle Weise. Er wird verstehen, wie Entwickler arbeiten!

Zusätzlich würde ich sagen, versuchen Sie, Diagramme zu verwenden, wie viele Leute bereits erwähnt haben. Aber denken Sie auch hier ernsthaft darüber nach, ihm die hier gegebenen Antworten zu zeigen!

0
bool.dev

Sie müssen zunächst den Umfang der Anfrage ermitteln. Sie müssen sicherstellen, dass Sie den Bossster unter dem Schreibtisch nicht erschreckender machen als das Monster tatsächlich ist.

Ist es mehr: // Die Methode bekommt einen Kunden. Oder mehr: // Einige ausführliche Programmiererklärungen, einschließlich was ist ein int, was bedeutet "void" und beinhaltet Mathematik, die in englische Konzepte umgeschrieben wurde?

Wahrscheinlich liegt es irgendwo dazwischen.

Wenn sich herausstellt, dass die Anfrage zu extrem ist:

Ich würde vorschlagen, dass Sie Ihrem Chef erklären, dass Programmierer, obwohl es wie eine kleine Sache erscheint, nicht dazu ausgebildet sind, sich auf diese Weise auszudrücken, außer im allgemeinsten Sinne des Codes. Es gibt Menschen, die darin geschult sind, Laien komplexe Ideen zu vermitteln. Sie werden als technische Redakteure bezeichnet.

Ein Problem, von dem ich denke, dass es nicht gut oder überhaupt nicht angesprochen wurde. Zu diesem Zweck sollte der Code geschrieben werden. Ist ihm bewusst, wie viel Zeit dies verbraucht, wenn er versucht, die Fristen einzuhalten?

Angesichts der Tatsache, dass diese Art von Kommentaren nicht im Code enthalten sein sollte, gibt es keine gute Möglichkeit oder kein gutes Werkzeug (das mir bekannt ist), um diese Funktion zu erfüllen.

Dies ist ein Wartungsalptraum. Selbst wenn eine Methode gefunden wird, die dies beim Generieren von Code bewirkt, wie würden die Kommentare beibehalten, sobald der Code in die Wartung eingeht?

Wenn Sie nach einem Chat glauben, dass Ihr Chef es immer noch nicht versteht, suchen Sie nach neuen Jobs. Die Person, die nur eine einzige verrückte Idee hat, ist seltener als ein Einhorn.

Und wenn diese Person Codedateien öffnet, hoffe ich, dass Sie eine wirklich gute Quellcodeverwaltung haben.

0
user179700

Im Idealfall sollte jeder Code für Ihre Kollegen oder Ihren Chef lesbar und verständlich sein. Wenn Ihr Chef dies wünscht, ist Ihr Code nicht ausdrucksstark genug und kommuniziert Ihre Absicht nicht gut genug. Erzählen Sie Ihren Code nicht, schreiben Sie Ihren Code so, dass er so weit wie möglich einer englischen Erzählung ähnelt! Weitere Informationen finden Sie unter Domain Specific Languages ​​(DSLs).

Einige Links:

0
thSoft

Ich würde ihm nur das Video zeigen Schnell sortieren mit ungarischem (Küküllőmenti legényes) Volkstanz und ihm dann erklären, wie lange Dies würde für alle Codezeilen erforderlich sein.

0
Petter

Es ist eine sehr unvernünftige Bitte. Sie müssen Code und Programme schreiben, und jede Dokumentation, die Sie schreiben, soll anderen Entwicklern oder Programmierern helfen, die an demselben Projekt arbeiten - nicht Ihrem Chef oder Mitarbeiter.

0
Michell Bak

Ähm ...

Haben Sie Ihren Code aus einer Spezifikation erstellt? Wurde die Anforderung korrekt dokumentiert?

Wenn er ein halbwegs anständiger Manager ist, sollte er fragen: "Entspricht dies den Anforderungen?"

Wenn Sie zu dem oben Gesagten Ja gesagt haben ... geben Sie ihm diese Dokumente + das Zeug, das Sie bereits erwähnt haben. Wenn er noch mehr will, ist er ein Idiot und sollte eindeutig kein Entwicklerteam leiten.

Und bevor dieser Dummkopf mit "Nun, was wissen wir" zurückkommt ... Ich wette, dass es allein in diesem Thread mindestens 50 Jahre kombinierte Erfahrung gibt.

Rolle eines Managers: 1. Identifizieren und Zuweisen von Zielen. 2. Stellen Sie sicher, dass sie korrekt ausgeführt werden. 3. Stellen Sie keine dummen Fragen, die bereits beantwortet werden sollten.

Ehrlich gesagt, wenn Sie bereits eine Lösung erstellt haben, sollte er wissen, was geschrieben wurde. Wenn er keine Ahnung hat, was Sie tun, dann hat wohl Smoeone über ihm Details darüber verlangt, was sein Team vorhat.

Sie könnten wirklich klug sein und Ihre Lösung wieder mit dem Geschäftsplan verknüpfen und zeigen, wo Sie die Kernziele des Geschäfts erreichen. Dann geben Sie die Details an seinen Vorgesetzten weiter und erklären, dass Ihr eigener Manager Sie nicht verstehen kann.

Sie werden wahrscheinlich seinen Job bekommen.

Ich wurde ausdrücklich gebeten, zeilenweise (oder gegebenenfalls - z. B. Bild für Bild usw.) Erklärungen/Kommentare zu geben, die mein Chef lesen und befolgen möchte.

Gib ihm ein Flussdiagramm lol ...

Entweder das oder er fragt nach Benutzerdokumentation?

0
Paul

Ich möchte Ihren Chef auch darauf hinweisen, dass dies X Stunden Ihrer Zeit in Anspruch nehmen würde. Nachdem er gesehen hat, was dies bedeuten wird, wäre ich überrascht, wenn er Sie bittet, fortzufahren.

Ich würde ihn/sie auch zu einer Codeüberprüfung Ihrer Funktion einladen. Nicht damit er/sie etwas verstehen kann, sondern nur um zu verstehen, dass Sie und Ihr Team dies intern tun, um Ihren Code NICHT verbalisieren zu müssen. Wenn Ihr Chef danach fragt, sagt mir mein Bauch, dass er Ihrem Team nicht vertraut oder dass es die gebotene Sorgfalt wendet. Wenn Sie ihn/sie durch eine Codeüberprüfung sitzen lassen, würde dies zeigen, dass die gebotene Sorgfalt und er/sie Sie hoffentlich in Ruhe lassen würden.

0
Rikon

Ja, ich stimme zu, dass es keine vernünftige Anfrage für uns ist, aber vielleicht ist er neugierig zu wissen, wie das alles funktioniert. Für einen Nicht-Programmierer würde ich also Flussdiagramm verwenden. Damit Ihr Chef das Gesamtbild sieht oder Sie in Flussdiagrammen gemäß seinen Anforderungen so viele Details wie Sie möchten ausführen können. Es sind viele Flussdiagrammanwendungen verfügbar. Ich fand Balsamiq Mockups hilfreich. Ich hoffe das hilft.

0

Ein Bild sagt mehr als tausend Worte. Zeichne einige Use Case und Sequence Diagramme. Sie sollten ausreichen, um den Zweck/Ablauf der Software zu erläutern.

P.S: Was auch immer Sie tun, vermeiden Sie es, Ihre Quelle mit Kommentaren zu füllen. Dies führt zu einem Aufblähen, insbesondere wenn es in einem Versionsverwaltungssystem gespeichert ist. Fügen Sie stattdessen einige Zahlen/Codes hinzu, die sich auf die vorgeschlagenen Diagramme beziehen.

0
James P.

Sie können auch einen Wechsel zu Literate Programming und COBOL oder FORTRAN vorschlagen, da https://stackoverflow.com/questions/152160/using-noweb-on-a-large-Java-project oder einfach fragen, warum Er verlangt nicht von jedem Graphiker, dass er jede einzelne Verwendung eines von ihm hergestellten Werkzeugs erklärt.

Wenn Sie ein Spezialist sind, wird von Ihnen erwartet, dass Sie ein High-End-Produkt liefern und nicht im Detail erklären, dass Sie hier einen grünlichen Strich malen und dann eine 2-Pixel-Gauß-Unschärfe usw. anwenden.

0
Kheldar