Wie kann ich anderen Entwicklern den Code besser erklären? [geschlossen]

Während die Frage selbst albern klingt, ist die Antwort für mich sehr wichtig, da ich der Meinung bin, dass dieses Problem meine Arbeitsleistung negativ beeinflusst.

Ein bisschen Hintergrundwissen hier: Ich bin ein erfahrener leitender Softwareentwickler in einer mittelgroßen Softwareabteilung eines Nicht-Software-Unternehmens. Obwohl ich technisch überdurchschnittlich gut bin, kann ich viel schlechter kommunizieren und erklären. Auch wenn man anderen Entwicklern etwas erklärt.

Die meisten Schwierigkeiten treten auf, wenn ich erkläre, wie ein bestimmtes kleines Stück Code funktioniert.

Das Lustige ist, dass es für mich viel einfacher ist, Beispiele dafür zu erklären und bereitzustellen, wie etwas auf einer viel höheren Ebene funktioniert, z. B. Interaktionen zwischen separaten Modulen und Subsystemen.

Um es klarer zu machen, nenne ich "Quellcode, der Fähigkeiten erklärt" a

a) Fähigkeit, den Ausführungsfluss des Codes klar zu erklären - z. B. "Dieses Ding ruft das Ding auf, das das Objekt zurückgibt, das später Methode A aufruft und das Objekt B an ... übergibt."

a) Fähigkeit, die Probleme mit einem aktuellen Design oder, was noch wichtiger ist, die Auswirkungen der Änderung des Quellcodes klar zu erklären, wie in "Wenn wir aus Leistungsgründen damit beginnen würden, das Objekt als Feld der Klasse zwischenzuspeichern, hätten wir." Änderungen an zehn verschiedenen Stellen vorzunehmen, um sicherzustellen, dass der Cache immer auf dem neuesten Stand ist "etc.

Ich habe versucht zu analysieren, warum ich schlecht darin bin, Dinge zu erklären, und habe keine Erklärungen gefunden, außer vielleicht, dass ich Dinge auf eine Art und Weise erkläre, die einige vielleicht zu starr finden. Auch wenn ich Dinge erkläre, konzentriere ich mich vielleicht zu sehr auf das, was ich selbst sage und vermisse die Fragen, was die Leute fragen, aber für mich scheint es, dass diese Fragen oft irrelevant sind und das Gespräch einfach wegziehen.

Was könnten Sie mir empfehlen (außer den offensichtlichen "Praktiken, die es perfekt machen", die ich nicht wirklich kaufe, da ich denke, ich würde wahrscheinlich immer wieder dieselben Fehler üben), damit ich die Quelle verbessern kann Code, der Fähigkeiten erklärt.

Eines der Probleme ist, dass kleine Codeteile nicht immer das Gesamtbild erklären. Wenn ich zum Beispiel unbekannten Quellcode in einer vertrauten Programmiersprache betrachte, verstehe ich normalerweise die meisten einzelnen Anweisungen. Gleichzeitig kann es schwierig sein, den unbekannten Algorithmus zu verstehen, zu dem sie beitragen, welche Rolle dieser Algorithmus in der Gesamtlösung spielt und warum dieser Algorithmus anderen Alternativen vorgezogen wurde. Obwohl ich diese Aussagen verstehe, verstehe ich sie gewissermaßen überhaupt nicht.

Ein Beispiel hierfür ist die klassische Fast Inverse Square Root- Funktion.

Einige Dinge, die ich im Umgang damit nützlich finde:

• Erklären Sie den Code in derselben Sprache, die die Benutzer verwenden.
• Erklären Sie den Code mit Standard-Programmierbegriffen, z. B. Begriffe wie "Puffer", "Liste", "Singleton", die den meisten von uns bekannt sind, ebenso wie gängige mathematische Begriffe.
• Erklären Sie, was Sie in Bezug auf die Ein- und Ausgänge tun.
• Erfinde Wörter für Konzepte, für die du keine Wörter hast. Manchmal verwende ich Wörter wie "Einsteller", "Kette" oder "Wrangler" als Abkürzung für einige sehr knorrige Konzepte. So wurden schließlich bekannte Begriffe überhaupt erfunden.
• Beachten Sie, dass die wenigen Codezeilen zwar an sich einfach erscheinen, ihre Rolle in einer größeren Codebasis jedoch recht komplex sein kann. Sie können sie nicht immer erklären, ohne viele Hintergrundinformationen bereitzustellen. Wenn dies der Fall ist, geben Sie es an.
• Nennen Sie konkrete Beispiele.
• Diagramme zeichnen .

Der Grund ist einfach. Sie denken wie ein Programmierer.

Konzepte auf hohem Niveau erklären zu können, ist das, was wir unser ganzes Leben lang tun, wenn wir Ideen vermitteln wollen. Wenn wir jedoch programmieren, stellen wir uns in die Denkweise, dass wir verstehen müssen, wie man Aufgaben in Bezug auf viele kleine und detaillierte Schritte erledigt. Das zu erklären bedeutet, dass Sie "kleine und detaillierte Schritte" in etwas konvertieren müssen, das jeder verstehen kann, was keine kleine Bestellung ist. Wenn solche Dinge leicht zu verstehen wären, könnte jeder programmieren. Das macht uns zu Programmierern.

Wie Sie wahrscheinlich erraten haben, ist es jedoch eine Sache, zu verstehen, wie Aufgaben in Form vieler kleiner und detaillierter Schritte ausgeführt werden, und eine ganz andere, sie gut zu erklären.

Auch ich hatte einige Schwierigkeiten bei diesem Unterfangen, aber ich habe bemerkt, dass mir einige Tricks geholfen haben. Angenommen, Sie haben eine Methode, die Sie geschrieben haben, und Sie müssen erklären, wie sie funktioniert:

• Bevor Sie mit der ersten Zeile beginnen, lesen Sie Ihre Methode und merken Sie sich, welchen Umfang sie hat, welchen Zweck sie erfüllt, wann sie aufgerufen wird und warum Sie sich auf diese Weise dazu entschlossen haben. Kurz gesagt, wissen Sie, was es tut. Auf diese Weise können Sie Fragen gründlich und auf eine Weise beantworten, die den Sinn der Methode umfasst (dh wenn sie sagen "Ich verstehe den Punkt dieser Zeile nicht", können Sie antworten: "Dies ist das, was instanziiert die Verbindung zur Datenbank, die im gesamten Programm verwendet wird "anstatt" Das ruft den JDBC auf, der die Verbindungszeichenfolge verwendet, um eine Verbindung herzustellen ", die die Frage beantwortet, aber wahrscheinlich nicht das ist, was es klar macht).
• Erläutern Sie jede Zeile in der Methode im Hinblick darauf, was jede Zeile zum Gesamtzweck der Methode beiträgt. Warum hast du diese Zeile dort gesetzt? Oh, richtig, diese Zeile ruft die Klasse auf, die für die Eingabeverwaltung verantwortlich ist, um zu überprüfen, ob ich Aktionen in meiner Renderschleife delegieren musste.
• Geben Sie zu, wenn Ihr Code möglicherweise unklar ist oder verbessert werden könnte. Wenn Sie Code finden, der möglicherweise unklar ist, schreiben Sie ihn neu, um ihn klarer zu gestalten. Es hilft der Kommunikation nicht, Ihren Programmierkollegen zu frustrieren, zu denken, er sollte verstehen, was er sieht.

Konzentrieren Sie sich im Allgemeinen darauf, warum Sie diesen Code dort ablegen und nicht darauf, was er tut, und Sie werden feststellen, dass Ihre Erklärungen leichter fließen und leichter zu verstehen sind.

Ich habe mich auch in einer ähnlichen Position befunden, die manchmal mit der Erklärung des Ausführungsflusses von Code auf niedriger Ebene zu kämpfen hat. Was mir geholfen hat, war, den fraglichen Programmiersprachenführer (Bjarne Stroustrups Programming in C ++) in die Hand zu nehmen, um mich über die Terminologie zu informieren, die im Laufe der Jahre unvermeidlich verblasst war. Lesen Sie außerdem neue sprachrelevante Artikel / Blogs, um über aktuelle Techniken / Begriffe auf dem Laufenden zu bleiben.

In Bezug auf komplexe Designprobleme / Implikationen: Es ist in Ordnung zu sagen, dass ich Ihnen keine Antwort geben kann, ohne mehr Analysen durchzuführen, ohne eine sofortige Antwort zu geben. Software kann sehr komplex werden und selbst die klügsten Entwickler können nicht immer alle Interaktionen im Kopf behalten - außerdem sind wir alle Menschen und verstehen Dinge falsch oder verpassen Dinge.

Nehmen Sie sich Zeit, um den Code zu analysieren, damit Sie sich Ihrer Antwort sicherer sein können. Es wäre sicherlich besser, als eine sofortige, möglicherweise falsch informierte und falsche Antwort zu geben. Von einer Position als leitender Entwickler aus würde es als Weisheit angesehen werden und zu Ihren Gunsten gehen, anstatt reaktionsschnell, aber möglicherweise dumm auszusehen!