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

Ich wurde ausdrücklich gebeten, zeilenweise (oder entsprechend - zum Beispiel Bild für Bild usw.) Erklärungen oder Kommentare abzugeben, die mein Chef lesen und befolgen kann.

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

Wurde schon jemand dazu aufgefordert?

Ich habe den gesamten Quellcode kommentiert und JSDoc verwendet , um eine vollständige Dokumentation aller Funktionen, Variablen usw. zu generieren. Außerdem habe ich ein Implementierungsbeispiel und vollständige funktionierende Demos mit Kommentaren hinzugefügt.

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

Das ist keine vernünftige Bitte, oder?

AKTUALISIEREN

Am Ende gelang es mir zu erklären, warum es nicht gut war, die Zeit zu nutzen, um das zu tun, was er verlangte. Er ist ein vernünftiger Typ und hatte einfach kein Verständnis dafür, was meine Arbeit beinhaltet. Als er diesen Beitrag sah, wurde ihm schnell klar, dass dies keine normale Anfrage war.

Ich habe eine Dokumentation zur Verfügung gestellt, 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, der mein Chef folgen soll.

Am Ende waren alle Parteien zufrieden und wir sind weitergezogen.

Nein , es ist keine vernünftige Bitte!

SPRECHEN SIE IHN AUSSERHALB , oder lassen Sie ihn auf alle Fälle von jemand anderem ausreden. Das ist eine irrationale Idee, die, obwohl machbar, so teuer ist, 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 etwas nicht in englischen Text zu übersetzen. Obwohl dies sicherlich möglich ist, birgt dies viel Raum für Fehler und Fehlinterpretationen und sollte niemals getan werden. Genau wie das "Übersetzen" von Code ins Englische.

Haben Sie Konstruktionsunterlagen ? Dies ist die englische Erklärung der Funktionsweise des Codes. Ein Manager ohne Programmierkenntnisse sollte nicht mehr benötigen.

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, er müsse den Code Zeile für Zeile verstehen können, aber nicht lernen möchte, wie man ihn direkt liest, ist so perfekt wie ein Mikromanager.

Ein Vorteil eines Entwicklers besteht darin, dass die Schwierigkeit, Code zu verstehen, ein Mikromanagement über einen gewissen Grad hinaus verhindert, zumindest auf der detaillierten Implementierungsebene, zumindest durch nichttechnisches Management, da selbst der schwierigste Mikromanager erkennt, dass dies der Fall ist über den Kopf auf dieser Ebene. Aber das Genie Ihres Chefs könnte einen Weg finden, den Silikonvorhang zu zerbrechen.

Und als Bonus verschwendet es enorm viel Entwicklerzeit für die Übersetzung, noch bevor er die englische Übersetzung verwendet, um verschiedene Verbesserungen vorzuschlagen (ich nehme an, er kann besser als die Programmierer programmieren, obwohl er es nicht kann Lesen Sie den Code und teilen Sie seine Weisheit mit, sobald jemand ihn übersetzt. Warum sollte er sonst jede Zeile übersetzen lassen?

Also, nein, es ist keine vernünftige Bitte, und ich habe noch nie davon gehört. Und ich fühle für dich. Ich denke, dass jeder anfangen muss, leise nach einem anderen Job zu suchen, denn sobald er die Code-Übersetzung als Management-Tool einsetzt, wird es wahrscheinlich ein brutaler Ort zum Arbeiten (äh, ein brutaler Ort zum Arbeiten).

Auf der positiven Seite können Sie vielleicht ein neues Anti-Pattern erhalten, 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 mit komisch falschen Übersetzungen verwendet?

Setzen Sie sich mit 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 dann wissen können, was einzubeziehen und was wegzulassen ist? Wie lange hätte es gedauert, bis die Ergebnisse für Sie von Nutzen wären? Nun, wie viele Zeilen soll ich auf diese Weise machen?

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

Vielleicht hat er Angst, Sie könnten Ihren Code dazu bringen, etwas zu tun, das er nicht billigt oder dessen er sich bewusst ist. Wenn das der Fall ist, gibt es meiner Meinung nach nichts, was Sie dagegen tun können. Sie müssen die Dokumentation schreiben oder ihn / sie davon überzeugen, jemanden einzustellen, der Ihren Code überprüft.

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 erwarten können, dass er Ihre Handlungen vollständig versteht

Ich habe in einem früheren Job ähnliche Erfahrungen gemacht. Mein Manager war ein Buchhalter (und daher sehr detailorientiert) und verstand die Programmierung nicht oder vertraute ihr nicht wirklich. Sie konnte nicht begreifen, dass sie als nicht-technische Person nicht erwarten sollte, die Minutien von dem, was ich schrieb, erfassen zu können. Nach vielen Anfragen nach übermäßiger Dokumentation und Aufforderungen, nicht-technische Benutzer in der Verwaltung und Änderung des Codes zu schulen (ja, wirklich), hörte ich auf, sie abzuspeisen, und lehnte dies endgültig ab. Die Analogie, die ich zu erklären pflegte, 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, indem man der Person vertraut , die sie erstellt hat

Am Ende klingt das für mich so: ein Manager, der Schwierigkeiten hat, seinen Mitarbeitern zu vertrauen; oder befürchtet, dass sie gehen 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 zu ermöglichen, ihn zu verstehen, nicht Ihrem Manager. Ihnen diesen Thread zu zeigen, mag eine gute Idee sein (oder eine wirklich, wirklich schreckliche, abhängig von ihrer Persönlichkeit).

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 Prüfungen der kanadischen Regierung, an denen ich in der Vergangenheit gearbeitet habe.

Er wird nicht Zeile für Zeile erhalten, sondern Methode für Methode, 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 in gewissem Maße D." : Sauerstoff

Es wäre für ihn viel schneller, das Lesen von Code zu lernen, als den gesamten Code einer interessanten Anwendung auf Englisch zu übersetzen. Außerdem haben wir das mit COBOL versucht und es hat überhaupt nicht geholfen. Wenn er nicht lernwillig ist, sondern nur das Problem eines anderen ignorieren möchte, dann haben Sie einen ernsthaft spitzen Chef.

Nutzen Sie Ihr technisches Know-how, um Ihren Chef zu verfolgen.

1. Lassen Sie ihn wissen, dass es genauso lange dauern wird, wie Sie es getan haben, um es an erster Stelle zu codieren (Sie können es auch gerne verlängern.).
2. Fragen Sie ihn, wie aktuell dieses Dokument sein muss. Informieren Sie ihn, dass alle Codierungsänderungen mindestens doppelt so lange dauern.
3. Wenn Sie oder jemand anderes Fehler findet, fragen Sie ihn, ob Sie diese jetzt beheben sollen, oder warten Sie, bis Sie mit der Pseudocodierung fertig sind. Erinnere 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, dass er nicht antworten kann. Es könnte einen bestimmten Codeabschnitt geben, der ihm am meisten Sorgen bereitet, also könnten Sie dieses massive Unternehmen auf genau diesen Bereich beschränken.

Durch das Einreichen eines Musters kann er zu dem Schluss kommen, dass es keine Rolle spielt, in welcher Sprache es ist, wenn Sie nicht verstehen, wie das Codieren funktioniert (Was ist eine Schleife und was macht es mit all diesen Elementen?). Er ist besser Aus 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.

Warum?

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

Ist es weil...

• Sie möchten ein vollständiges Verständnis dessen, was die Software macht (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 ein vernünftiger Wunsch dahinter, und Sie können Ihren Chef möglicherweise glücklich machen, indem Sie dies herausfinden und diesem Bedürfnis nachkommen.

Aktualisieren

Gestützt auf einen Mikey'sKommentar habe ich dies vielleicht etwas zu unverblümt angegeben. Ich meine nicht, dass du buchstäblich sagen sollst "Warum willst du das?", Nur dass du das herausfinden solltest . Wortlaut und Tonfall machen einen großen Unterschied. Konkret könnte man so etwas sagen:

"Ich habe über Ihre Bitte nach einer Erklärung für jede einzelne Codezeile nachgedacht. Es ist ein bisschen ungewöhnlich, Dinge auf diese Weise zu tun. Ich habe mich gefragt, ob ich Ihnen vielleicht etwas nicht gut über meine Arbeit mitteilen kann. Was ist es, was Sie wirklich über unseren Code verstehen wollen oder was ich tue? Was versuchen Sie hier zu erreichen? "

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

Wenn nicht, fangen Sie an, Ihren Lebenslauf zu polieren. :)

Hört sich nach einer guten Gelegenheit an, das Programmieren zu erlernen. Google es. :)

Aber ... es ist nicht unbedingt eine völlig unvernünftige Bitte. Ein Teil Ihrer Aufgabe (der wichtigere Teil, imo) besteht darin, Ihre Algorithmen anderen Entwicklern und gegebenenfalls nicht-technischen Mitarbeitern mitzuteilen. Ich denke, einsame Genie-Programmierer, die nicht kommunizieren können, sind immer problematisch.

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

Selbst eine zeilenweise Übersetzung vermittelt nicht effektiv die Bedeutung jeder Codezeile. Das Verständnis eines Programmierers für eine Codezeile hängt immer von vielen Faktoren ab. Steigen Sie in so etwas wie einen Multithread-Code ein, und die englische Übersetzung ist nicht sinnvoller als der Rohcode. Denken Sie an Funktionen, die auf mehrere Funktionen / Dateien verteilt sind. Einige Codes machen überhaupt keinen Sinn, ohne umfangreiche Informationen zu anderen Codes zu liefern. Versuchen Sie, die verschiedenen Teile der Abhängigkeitsinjektion "zeilenweise" zu erklären, und Sie werden sehen, was ich meine. Nahezu alles, was über den Verfahrenscode für Gottfunktionen hinausgeht, erfordert umfangreiche Programmierkenntnisse, um die englische Übersetzung zu verstehen. Schauen Sie sich auch etwas so Einfaches wie eine if / else-Entscheidung an. Es gibt keine Zeile für Zeile, da die nächste Zeile von Laufzeitdaten abhängt. Die nächste Zeile könnte eine von mehreren Möglichkeiten sein.Bis Sie erklärt haben, was Ihre Anwendung bewirkt, haben Sie aus Ihrer PM einen Programmierer gemacht, und Sie sind beide 5 Jahre älter.

Da ich früher Programmieren unterrichtet habe, 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 gerne Dinge erkläre :-)

Wenn Sie sich auf Ihren "Chef" beziehen, ist dies "ein für Sie / Ihr Team zuständiger mittlerer Manager"? oder der Inhaber Ihrer Firma? Werden Sie "stundenweise" oder "nach Gehalt" bezahlt?

Wenn Ihr Chef ein rechenschaftspflichtiger Manager der Mittelschicht ist, weisen Sie darauf hin, dass Ihre Produktivität für das Unternehmen auf 1/3 des möglichen Wertes reduziert wird, um die Anforderungen Ihres Chefs zu erfüllen.

WENN Ihr Chef "derjenige 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.

Ein Flussdiagramm wird ihm wahrscheinlich mehr Nutzen bringen. Dies ist sicherlich eine ungewöhnliche Bitte und sagt nicht viel über ihn als Manager aus.

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 ihm Cucumber vorzustellen: http://cukes.info/

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

Er sollte sich nicht die Mühe machen, etwas davon zu wissen. Sagen Sie ihm, dass die Implementierung in der Softwareentwicklung Änderungen unterworfen ist. Eventdesign ist freibleibend. Erzählen Sie ihm von versteckten Informationen, deren Einkapselung und Abstraktion.
Er, als Teil Ihres Teams, als Kunde Ihres Codes im weiteren Sinne, sollte nur mit einer klaren Abstraktion auf hoher Ebene dessen arbeiten, was Ihr Code tut. Auf die gleiche Weise funktioniert jede Codeschicht mit einer anderen Codeschicht eines anderen Benutzers. Mehr als das zu wissen, wird ihn nur verlangsamen und riskieren, dass er Annahmen trifft, die auf der inneren Funktionsweise Ihres Codes beruhen. Diese Annahmen werden aufhören zu gelten, wenn Sie Ihren Code ändern müssen, was zu einem Problem wird, wenn er darauf aufbauend ein System oder einen Prozess erstellt.
Und wenn Sie diese Art von Arbeit erledigen müssen, wird dies Ihre Effizienz verringern. Sie müssen nicht nur an zwei verschiedenen Stellen nachträgliche Änderungen vornehmen, sondern dies wirkt sich auch negativ auf Ihre Arbeitsmoral aus, was Ihre Leistung noch weiter verringert.

Das Schöne an Englisch ist, dass es wunderschön verschleiert. Wenn Sie dies zu Ihrem Vorteil nutzen, werden Sie diese Art von Anfrage möglicherweise nie wieder bearbeiten müssen. Ich würde ein kleines Stück des Codes als Beispiel nehmen, aber eines, das sehr abstrakt und überhaupt nicht leicht zu verstehen ist. Ich würde dann die Kommentare in technischem Englisch verfassen, als würden Sie sie für ein Kapitel in einem Programmierbuch verfassen. 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% der tatsächlichen Codebasis ist (verwenden Sie tatsächliche Zahlen auf der Basis von Codezeilen, wenn Sie können, sie sind wahrscheinlich schlechter als diese). Wenn er merkt, dass er keine Ahnung hat, was die englische Übersetzung sagt, und dass es 20.000 Mannstunden dauern wird, bis er diese Dokumentationsstufe erreicht hat, wird er ziemlich schnell zurücktreten. Aber sei sehr ernsthaft bemüht, seine Aufgabe zu erfüllen. Versuchen Sie es nicht, wenn Sie das nicht schaffen und er den Verdacht hat, dass Sie gegen ihn spielen.

Das sieht aus wie ein Kandidat für einen speziellen Urlaubsthema-Spitzhaar-Boss- Dilbert- Strip! Seine Bitte klingt auf den ersten Blick sicher 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, die Sie benötigen, um seine scheinbar bizarre Bitte zu erfüllen, und entscheiden Sie dann, 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!

Bringen Sie ihn in Ihr Büro und zeigen Sie ihm Ihren Code.

Er wird auf halbem Weg erkennen, dass er eine absurde Forderung gestellt hat, und er wird weggehen und dich nie wieder belästigen.

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

Dies ist ein Fall, in dem Beschwichtigung besser wirkt als Abrieb.

Es wäre sehr schön, wenn wir einen Übersetzer "Language X to English" hätten, der das macht. Dann könnte man grinsen und sagen, kein Problem, Chef, 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
• Erhöhe x um 1
• ....

Eine andere Möglichkeit wäre, von nun an die Programmierung in Shakespeare vorzuschlagen .

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 Dokumentation auf hoher Ebene bereit.

Das ist keine vernünftige Bitte, oder?

Nein.

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 Bitte Ihres Chefs "verletzt" Ihren ersten Job. Die Dokumentation Ihrer Programme nimmt mehr Zeit in Anspruch. Andererseits bringt er Sie dazu, bei Ihrem "zweiten" Job härter zu arbeiten.

Ihr Chef bittet Sie, Ihr Programm in englischer Sprache zu dokumentieren, zum Wohle der KIS und vermutlich zum Wohle 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 nach mehr Hardware, Personal oder Geld für Raises fragen. Immerhin hat er dich gebeten, mehr zu arbeiten.

Ich denke, BDD würde gut zu diesem Problem passen, auch wenn es so aussieht, als ob Ihr Projekt kurz vor dem Abschluss stünde. Es ist also ziemlich schwierig, es jetzt zu implementieren, sodass es eher als zukünftige Referenz dient.

Mit BDD werden Use-Cases als lesbare Dokumente beschrieben, die dann in automatisierte Funktionstests übersetzt werden.

Wahrscheinlich ist diese Anfrage ein guter Zeitpunkt, um Dinge wie ANTLR zu lernen . Nehmen Sie ANTLR, nehmen Sie die Sprache der Grammatik, analysieren den gesamten Code Sie haben, durchqueren Sie Ihre AST Erzeugungs Template-basierten Beschreibungen für jeden Knoten, so i++wird wie folgt beschrieben increase i by 1 using postfix increment operator. Das sollte echt lustig sein. Ihr Chef möchte möglicherweise auch, dass dieses Tool in das Build-Skript aufgenommen wird. Bei jeder Änderung erhalten Sie eine E-Mail mit einer Beschreibung der neuen Version (ca. 20 MB).

PS Nur ein Scherz, er ist ein Idiot.

Obwohl ich zustimme, dass dies eine unvernünftige Aufforderung ist, schätzt Ihr Chef möglicherweise etwas wie die Ausgabe von Docco , bei der Code und zeilen- oder klauselweise Kommentare in zweispaltige HTML-Ausgaben mit dem Code eins aufgeteilt werden Seite und Prosa auf der anderen Seite. Sie müssen die Kommentare natürlich selbst eingeben, aber die Präsentation ist meiner Meinung nach auch für nicht-technische Leser recht nett. Siehe z. B. einen zeilenweise kommentierten Abschnitt des mit Anmerkungen versehenen Codes für Underscore.js . Es gibt auch Python- und Shell-Skriptversionen.

Es ist möglich, dass Ihr Chef nicht informiert und eingeschüchtert ist, aber tatsächlich eine vernünftige Person ist. In diesem Fall könnte es hilfreich sein, mit ihm / ihr zu argumentieren - ein ungezwungenes Gespräch, bei dem Sie versprechen, "das zu liefern, was er wirklich will", z. eine Prosa-Anleitung zu dem, was das Programm tut.

Wenn es auf "meinen Weg oder die Autobahn" ankommt, prüfen Sie jetzt besser Ihr Benzin.

Sie könnten einige Akzeptanztests mit einem verhaltensgesteuerten Design-Framework wie Gurke schreiben ? Das wird den Code nicht erklären; es wird erklären, was es tut, und 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 Test-Runner rot.

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

Ihr Vorgesetzter 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, 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 vernünftig. Aber das liegt hauptsächlich daran, dass er nicht versteht, was Programmcode 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 der Algorithmus offenbart wird, der gleichermaßen 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, während die Kommentare erläutern, was die einzelnen Zeilen bewirken, immer noch keine Ahnung haben, was der Code wirklich bewirkt, es sei denn, Sie wissen, welche Auswirkungen dies hat. Es ist offensichtlich, dass Sie ein Programmierer sind und dieses Muster schon einmal gesehen haben. Zeigen Sie dies jedoch jemandem, der nur mit Verkäufen vertraut ist, 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 Programmierkenntnisse beibringen. Wenn er Ihren Code lesen möchte, geben Sie ihm die Werkzeuge, um dies zu tun. Die meisten Sprachen sind syntaktisch recht 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 Ihren Code nicht lesen möchte.

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