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

155

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.

Billy Moon
quelle
Aus historischen Gründen gesperrt. Weitere Informationen finden Sie unter " Gesperrte, am häufigsten gestimmte Fragen" .
Yannis

Antworten:

160

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.

Rook
quelle
Interessant: Lesen Sie Richard Feynmans Vorlesungen über Physik. Sie werden feststellen, dass vieles davon ein sorgfältig formuliertes Argument auf Englisch ist (wenn X, dann muss Y wahr sein, und daher Z ... usw.). Kleine Mathe. Der Punkt, den ich anspreche, ist, dass Sie Dinge auf Englisch erklären können. Ob Sie sollten, ist eine andere Sache.
quick_now
1
@quickly_now - Lies sie vor langer Zeit während des Studiums. Keine schlechte Lektüre. Ich stimme dir zu, du kannst es erklären - du kannst es in jeder Sprache erklären, wenn die Person, die du erklärst, bereits die "Abstraktion" dahinter versteht (Code, mathematische Gleichung und Bedeutung davon ...) // Wenn er es nicht tut ' t - Sie werden Schwierigkeiten haben, es in einer beliebigen Sprache zu erklären.
Rook
4
@Rook - guter Punkt. Die Quantenmechanik einem primitiven Stamm zu erklären, dessen Wortschatz auf die Richtung beschränkt ist, in die sich die Elche bewegten, wäre ein bisschen schwierig.
quick_now
Ich könnte die "Absicht" Ihres Managers manchmal bekommen, Mikromanagement zu betreiben. Aber wenn der Code an sich sehr klar war, kann er ihn einfach als englischen Text lesen.
Arvind Chinniah
150

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

xtian
quelle
15
Aus diesem Grund habe ich angegeben: "Ein Manager ohne Programmierkenntnisse sollte nicht mehr als das benötigen."
Malfist
35
@Loren Pechtel: Ich möchte dort eine Site erstellen und beobachten, wie dieser Typ tatsächlich Seiten von "Erstellen einer Ganzzahlvariablen mit dem Namen X" liest. Setzen Sie sie auf 0. Erstellen Sie eine Ganzzahlvariable mit dem Namen Y. Setzen Sie sie auf 0. Erstellen Sie eine Ganzzahlvariable mit dem Namen Z Setzen Sie es auf 0. Erstellen Sie eine ganzzahlige Variable mit dem Namen X-Position. Setzen Sie es auf 0. Erstellen Sie eine ganzzahlige Variable mit dem Namen Y-Position. Setzen Sie es auf 0. Erstellen Sie eine ganzzahlige Variable mit dem Namen Z-Position X-Drehung. Setzen Sie ihn auf 0. Erstellen Sie eine Ganzzahlvariable mit dem Namen Y-Drehung. Setzen Sie ihn auf 0. Erstellen Sie eine Ganzzahlvariable mit dem Namen Z-Drehung. Setzen Sie ihn auf 0. "...
FrustratedWithFormsDesigner
9
@Frustated Mit Syntax-Hervorhebung ist es viel einfacher! " [p32767, l21, c8] Erhöhen pXum die Größe von Integer. Erhöhen Sumum den Wert, auf den durch verwiesen wird pX. Erhöhen ium 1. Wenn ikleiner als 3, fahren Sie mit Seite 32768, Zeile 17, Spalte 42 fort. Andernfalls fahren Sie mit Seite 32767 fort , Zeile 21, Spalte 8. "
Mateen Ulhaq
9
@muntoo, Sie müssen alle diese Funktionen einbinden, damit Sie nicht zwischen den Seiten hin und her springen müssen. Andernfalls könnte es sehr schwierig werden, den Stapel wieder aufzubauen.
Kibbee
15
@Frustrated: Also, wessen Stimme stellst du dir vor? Ich kann mich nicht zwischen Sean Connery und Morgan Freeman entscheiden.
Beta
113

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?

bA
quelle
21
+1 für die Diagnose von Mikromanagement. In meinen eigenen Worten: Holen Sie sich die F___ da raus!
tdammers
@tdammers: Zum Glück kann ich meinem Chef so etwas sagen. Er ist ein guter Kerl, abgesehen davon, dass er ein Boss ist!
Heltonbiker
5
Ein Manager, der jede Codezeile verstehen muss, wird als Programmierer bezeichnet.
James P.
91

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?

reinierpost
quelle
57
Stellen Sie nach zwei Stunden Erklären von zehn Zeilen sicher, dass er weiß, dass noch 50.000 (oder was auch immer) Codezeilen zu erklären sind.
HLGEM
6
Eigentlich ein sehr vernünftiger Weg, um weiterzumachen. Lassen Sie ihn die Unwissenheit seiner Wege erkennen.
Kibbee
4
@reinierpost: deine methode ist pure genialität.
Heltonbiker
5
Wenn Sie dies tun wollen, sagen Sie zuerst dem Chef, warum es im Allgemeinen eine schlechte Idee ist, und demonstrieren Sie dann. Wenn Sie dies nicht tun, scheint es, als würden Sie ihm einen "Trick" auferlegen und ihn in die Defensive führen.
Nerdytenor
5
Sag den Leuten niemals, dass ihre Ideen schlecht sind !! Sie können jedoch diskutieren, was erforderlich ist, um sie zu verwirklichen, und vielleicht sogar einige Ideen für die Verwendung von Verknüpfungen geben. Wenn sie daraus den Schluss ziehen, dass die Idee nicht realisierbar war oder dass sich die ursprüngliche Idee in etwas völlig anderes verwandelt, und sie dies irgendwann bemerken sollten, werden sie mit den Schultern zucken und sagen: So ist das Leben.
reinierpost
43

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.

Pablo Santa Cruz
quelle
13
Selbst mit einer englischen Übersetzung kann ein Nicht-Programmierer sehr wohl glauben:/* and this line is transferring deposits to the correct account */ deposits.TransferAll(acctInfo);
IAbstrakter
15
Wenn der Chef "Angst hat, dass Sie Ihren Code dazu bringen, etwas zu tun, das er nicht billigt oder sich dessen bewusst ist", wird dies nichts dazu beitragen, seine Befürchtungen zu zerstreuen. Dieselbe Person liefert die Übersetzung, die den Code geschrieben hat. Was hindert sie daran, darüber zu lügen, was es tut? Hier ist noch etwas los.
MMC
4
COBOL sollte auf Englisch gelesen werden.
Oosterwal
1
Vielleicht versucht er herauszufinden, was der Code tut, um zu sehen, ob er mit der Argumentation einverstanden ist und vielleicht bessere Ideen bekommt. Auf jeden Fall ist es nicht seine Aufgabe, zumindest nicht so ...
heltonbiker
32

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).

John N
quelle
Wie hat Ihr Manager Ihre Erklärung aufgenommen?
Jeff Martin
1
Genau so, wie Sie es vielleicht erwarten. ;) Es wurde jedoch darauf hingewiesen und die Anfragen wurden gestoppt. Ich weiß nicht, ob das daran lag, dass ich sie von der Richtigkeit meines Arguments überzeugt hatte, oder sie entschied, dass es den Aufwand nicht wert war und gab auf.
John N
25

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
Steven Evers
quelle
Da es Pas2Dox gibt, füge Delphi zur Sauerstoff-Liste hinzu ;-)
Fabricio Araujo
Gehe zum Sandcastle-Link. Sehe beeindruckt aus. Klicken Sie auf die Registerkarte "Dokumentation". Siehe Meldung "Dieses Projekt hat noch keine Dokumentation." Sieh weniger als beeindruckt aus.
Kaz Dragon
16

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.

Kevin Cline
quelle
3
Ich denke, Englisch sollte die Sprache sein. Der Chef sollte darum bitten, dass die gesamte Software in einer DSL (domänenspezifischen Sprache) geschrieben wird, dann kann er Änderungen an der Funktionsweise des Systems vornehmen.
David d C e Freitas
Ich denke, die Erwähnung von Cobol bringt es auf den Punkt. Jeder, der eine einfache Hallo-Welt ausgedruckt hat, weiß, wie lächerlich wortreich diese Sprache ist. Es war ein guter Schritt zu etwas Verständlichem, aber viel zu Formalem.
James P.
15

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.

JeffO
quelle
7
Wir müssen vorsichtig sein, wenn wir jemanden als "Idioten" bezeichnen. Obwohl es für uns als Programmierer persönlich befriedigend ist, dies zu tun, halte ich es nicht für professionell, und jede Anfrage eines Managers, egal wie seltsam sie auch sein mag, sollte auf der Grundlage seiner Verdienste behandelt werden.
Funkymushroom
6
@funkymushroom: Der Verdienst dieser Anfrage ist, dass er ein Idiot ist.
DeadMG
3
@funkymushroom - Ich denke, wir können ein wenig Leichtsinn auf dieser Seite zulassen. Immerhin fährst du mit dem Funkymushroom.
JeffO
2
@ Jeff: Punkt gut getroffen. Ich bin keineswegs ein Stock im Schlamm. Es gibt jedoch zwei Arten von "Idioten". Der "Bösartige Idiot" und der "Ignorante Idiot" und ich haben mit beiden gearbeitet. Der erste sollte ignoriert werden, er ist gefährlich für unsere Karriere, und der zweite kann ein guter Verbündeter sein, also sollten wir ihn unterrichten.
Funkymushroom
@funkymushroom - stimme zu, also habe ich es rausgenommen.
JeffO
12

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. :)

Nathan Long
quelle
-1 für diese Antwort: Wenn Sie an Ihrem Job festhalten möchten (oder ihn zumindest freiwillig verlassen möchten), sollten Sie einen solchen Chef nicht fragen, warum. Dies ist etwas, das verfeinert werden muss, wie andere vorgeschlagen haben.
Vector
3
Ich bin mit Mikeys Kommentar nicht einverstanden. Es ist töricht, Befehle blind zu befolgen. Fragen, warum? Mit jeder Anfrage habe ich mir unzählige Stunden unnötiger Arbeit erspart und meinem Unternehmen dabei viel Geld gespart. Es heißt Beratung, und diejenigen, die ihre Chefs nicht fürchten, tun dies großzügig und mit großer Wirkung. Wenn Leute, die für mich arbeiten, etwas vorschlagen, frage ich sie auch, warum? auch. In beiden Fällen wird nach einer Rechtfertigung gesucht, und dies ist durchaus akzeptabel.
Soviut
10

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).

JohnL4
quelle
Ich habe mir die Wikipedia-Seite angesehen. Es erinnert mich an die "strukturierte <menschliche Sprache hier einfügen>", die ich während des Studiums gesehen habe. Sie verwenden die menschliche Sprache, um die Programmierstruktur zeilenweise mit Ausdrücken wie if blah then add 1 to xals Alternative zu nassi-schneiderman oder Flussdiagrammen darzustellen. Ist dies das, was mit Lese- und Schreibprogrammierung gemeint ist?
James P.
Du bist der einzige auf dieser Seite, der Knuths Lese- und
Schreibprogramm
@ James: Kaufen Sie ein Exemplar von Knuths "Tex - das Programm" und lesen Sie es. Das ist gebildete Programmierung.
cji
10

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.

Morgan Herlocker
quelle
10

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 :-)

Mike Dunlavey
quelle
3
Ich denke das ist die beste Antwort hier. Ich verstehe die Abneigung nicht, es zu versuchen, ich meine, Sie werden dafür bezahlt, dass Sie dort sitzen und Ihren Code erklären! Zum Teufel, es sei denn, Ihr Code ist total beschissen, Sie werden ihn wahrscheinlich genießen, und egal wie gut er ist, Sie werden wahrscheinlich einige Bugs und Verbesserungsmöglichkeiten finden.
Bill K
1
Ich hatte einen Lehrer, der Sachen erklärte, während er den Code abtippte, der über einen Projektor angezeigt wurde. Vielleicht könnte das ein bisschen wie eine Fahrstunde sein. Wenn Sie nicht den gesamten Code durcharbeiten können, können Sie einen besseren Eindruck davon bekommen, was und wie getan wird.
James P.
1
Ich versuche, selbst in das Lehrgeschäft einzusteigen, und habe eine ähnliche Antwort gegeben. Ich bin mit @Bill sehr enttäuscht, dass die Leute eine so zurückhaltende Haltung einnehmen würden. Sind wir verärgert, weil wir glauben, dass es sich lohnt, nur einen kleinen Teil des Codes zu erklären?
Rei Miyasaka
1
@Rei: Schlechte oder gute Einstellungen tendieren dazu, große Untergruppen ansonsten ähnlicher Personen zu übernehmen. Ich habe eine breite Erfahrung (Ingenieur, Student, Professor, Berater, Langzeitangestellter), daher denke ich gerne, dass dies eine Perspektive bietet. Auch meine Einstellungen haben sich im Laufe der Jahre verändert.
Mike Dunlavey
10

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.

Bildbeschreibung hier eingeben

Cos Callis
quelle
Warum nicht machen und das Geld nehmen? Sind Sie so sicher, dass Ihr einziger Wert darin besteht, Code wie einen Affen zu produzieren?
Bill K
9

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

James
quelle
18
Eigentlich sagt es mir viel über diese Person ...
Marjan Venema
5
Das ist es, worüber "nicht viel sagt" in diesem Zusammenhang bedeutet - es sagt zwar viel, aber es zeigt nur nicht viel Gutes über den Einzelnen an.
Joseph Weissman
8

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.

Mondblitz
quelle
Ich habe eine Weile versucht, Gurke in meinem Geschäft zum Einsatz zu bringen ... leider (oder vielleicht zum Glück!) Ist es meinem Chef egal, was hinter den Kulissen passiert, solange es funktioniert. Es war schon ein harter Kampf, ihn dazu zu bringen, die Vorteile des Testschreibens zu verstehen.
Jason Lewis
6

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.

back2dos
quelle
6

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.

HLGEM
quelle
6

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!

John Tobler
quelle
1
Eine Kosten-Nutzen-Analyse sollte den Job erledigen. Möglicherweise muss der Manager einige zusätzliche Vorteile einbringen. Wenn sich dies nicht auszahlt, ist es schwierig, das obere Management durchzusetzen und zu verteidigen.
mbx
6

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.

Rei Miyasaka
quelle
+1 - Ich habe in die gleiche Richtung gedacht - nimm ihn auf die Bitte an - er wird sich wahrscheinlich bald langweilen und / oder zu Tode erschrecken ...
Vector
+1 Ich mag das - "funktioniert besser als Abrieb".
Mike Dunlavey
6

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 .

Ingo
quelle
Ich würde den gleichen Vorschlag machen. Der Chef will keine konzeptionelle Übersicht, er will es Zeile für Zeile, damit es möglich sein sollte, an einem Tag etwas herauszuholen, das eine völlig nutzlose, aber oberflächlich korrekte Dokumentation erzeugt. Es spielt keine Rolle, ob es sich um ein Rattennest aus Wenn-Elsen in Perl handelt, das durch Eckfälle leicht zu verwechseln ist. Es werden lediglich Variablendeklarationen, Änderungen an Variablen, Methodenaufrufe usw. identifiziert Weg groks den Code).
PhilDin
Ja, dieser Chef ist nur unwissend. Er weiß nicht, was "Abstraktion" ist, er weiß nicht, dass Englisch nicht gut ist, um Computerprogramme auszudrücken, er kann sich nicht vorstellen, dass er wirklich nicht all diese Details wissen will, deshalb bezahlt er einen Programmierer. Deshalb verdient er eine Lektion wie diese.
Ingo
5

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.

Leichtigkeitsrennen im Orbit
quelle
4

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.

Tom Au
quelle
3
Zeile für Zeile dokumentieren! = Das Projekt verkaufen. Es sollte bereits ein Dokument geben, das diese Informationen enthält. Es wird Anforderungen genannt. Ich stimme Ihrer Beschreibung von 2 Jobs zu, aber eine Dokumentation auf dieser Ebene ist für den Verkauf des Projekts / Systems / der Anwendung nicht vorteilhaft. Es gibt eine angemessene Dokumentationsebene für die Präsentation Ihrer Arbeit, und das ist es nicht.
cdkMoose
Ich wette, die Person, die die Schecks bei diesem Unternehmen ausstellt, wäre nicht glücklich, wenn dieser Manager so viele Unternehmensressourcen verschwendet hätte.
JeffO
@ Jeff O: Könnte sein. Oder es könnte sein, dass das GANZE Unternehmen so ist, bis an die Spitze.
Tom Au
4

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.

Inoryy
quelle
Dies ist möglicherweise der konstruktivste Vorschlag, der bisher gemacht wurde. Behaviour-driven Development wurde entwickelt, um genau diese Anforderungen zu erfüllen: um Programmierern und ihren Managern / Kunden dabei zu helfen, sich über die Funktionen der Software zu einigen. Das Schreiben der Beschreibungen hilft beim Planen des Codes, und das Ausführen der Tests beweist, dass es sich immer noch um genaue Beschreibungen handelt.
Nathan Long
4

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.

Peter Mortensen
quelle
3

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.

btown
quelle
Dies ist eine der nützlichsten Antworten, die ich auf die Frage gesehen habe. Ich habe tatsächlich versucht, Docco zu verwenden, habe jedoch festgestellt, dass es Probleme mit einigen meiner vorhandenen Kommentare gibt, und habe es falsch gerendert. Ich habe mich daher stattdessen für JSDoc entschieden und die Richtlinien von Google befolgt, um die Dokumentation zu erstellen. Nicht so hübsch, aber sehr vollständig und auch ein Standardformat. Das Problem mit docco ist für mich, dass Sie Ihren Code so strukturieren müssen, dass er den Kommentaren entspricht, oder es macht keinen Sinn. Danke für den Vorschlag.
Billy Moon
3

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.

ddyer
quelle
3

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 ... ;-)

Peter Mounce
quelle
2

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.

tylerl
quelle
1

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

John K.
quelle
2
Beziehen Sie sich auf den Manager oder den Programmierer?
Nathan Long
Wie viele Unternehmen können es sich leisten, dass jeder nicht-technische Manager so viel Entwicklerzeit in Anspruch nimmt?
JeffO