Was ist die beste Plattform, um einem Entwickler, der nichts darüber weiß, Pseudocode zu erklären? [geschlossen]

8

Ich bin eine wissenschaftliche Person, die komplexen Matlab-Code dokumentieren muss, um ihn einem Entwickler zu übergeben, damit er ihn in einer anderen Sprache verstehen und programmieren kann. In der Vergangenheit habe ich MS Word (Erläuterung jedes Programmschritts als neue Zeile in einer Tabelle) und dann Excel verwendet, fand jedoch keine besonders gut geeignet, um meinen Matlab-Code anzuzeigen und Kommentare klar und präzise einzugeben Weg, um es zu dokumentieren.

Ich frage mich, ob es eine bessere Technik gibt, um einem Entwickler Pseudocode zu übermitteln. Gibt es eine vorhandene Software (kostenlos?) Oder eine andere Plattform (z. B. TextWrangler), die besonders für die Bereitstellung von Code und eine Methode zu deren Erklärung geeignet ist? In der Hoffnung, aus den Erfahrungen anderer zu lernen, die dasselbe tun. Danke im Voraus.

Lassen Sie mich nach dem Lesen einiger Kommentare versuchen, mehr zu erklären ... Ich gehe davon aus, dass alle Entwickler Pseudocode kennen, aber ich gehe nicht davon aus, dass viele Matlab-Code kennen. Wenn ich also in Pseudocode schreibe, kann ich den Matlab-Code ignorieren (oder ihn als Referenz usw. bereitstellen). Aber meine Frage ist wirklich einfacher ... gibt es Software oder Plattform, die in der Vergangenheit verwendet wurde, um einem Entwickler Code klar zu kommunizieren? Etwas, das es der Person, die das Dokument erstellt, ermöglicht, den Code einfach zu beschreiben? Sie können beispielsweise Code einbetten, den die Software farblich kodiert (eine Farbe für Kommentare, eine andere für reservierte Wörter (wenn, dann, sonst für usw.) usw.), und auf einer Seite kann ich Erklärungen eingeben und Referenzen usw. Ich habe versucht, dies mit MS-Produkten zu tun, dachte aber, da es eine Branche von Menschen gibt, die das Gleiche tun müssen,

pseudocode gkdsp
quelle
1
Ich frage mich, ob diese Frage nur schlecht formuliert ist oder ob ich sie falsch verstehe. Wie kann ein Entwickler nicht verstehen, was Pseudocode ist? Sprechen Sie über hochrangige Dokumente für die Funktionsweise des Programms?
Daenyth
4
Warum dem Entwickler Pseudocode geben? Warum geben Sie ihnen nicht den Matlab-Code und lassen ihn ihn selbst konvertieren? Ein anständiger Entwickler sollte in der Lage sein, Matlab zu lernen und herauszufinden, wie das Programm funktioniert.
FrustratedWithFormsDesigner
1
Ich denke, er beschreibt einen Entwickler, der nichts über MatLAB weiß, was sogar verständlich ist, da ersteres eine sehr nischenhafte Programmiersprache ist. Was ich vermute, dass das OP fragt, ist etwas in der Art von "Kennen Sie ein bewährtes System / einen bewährten Prozess / eine bewährte Prozedur, die den Übergang für jemanden, der MATLAB überhaupt nicht kennt, erleichtert, sich damit auseinanderzusetzen und den Code in eine andere Programmiersprache zu übersetzen?" "" Aber dann bin ich es nur, ich könnte mich irren!
Andrea Raimondi
1
Wort sollte geeignet sein. Es gibt zwei Ansätze, die Sie verfolgen können. Orientieren Sie die Seite im Querformat und präsentieren Sie Ihren MATLAB-Code auf der linken Seite und Ihre Anmerkungen auf der rechten Seite. Oder Porträt und Wechsel zwischen Code und Exposition.
GEL
1
Wenn ich der Entwickler wäre, würde ich wissen wollen, dass %ein Kommentar beginnt, und dann möchte ich erklärende Kommentare zum Matlab-Code hinzufügen. Und lassen Sie mich mit Fragen zu Dingen zurückkommen, die für mich keinen Sinn ergeben haben. Das wäre rundum am einfachsten.
Btilly

Antworten:

4

Setzen Sie den MATLAB-Code in ms-word. Ändern Sie die Schriftart in Kurier (Monospace), wenn dies hilfreich ist

Markieren Sie jede Zeile und geben Sie mit Kommentar einfügen (unter der Registerkarte Überprüfen in Word 2010) Ihre Erklärung ein

Der Entwickler kann das Gleiche tun. Wort macht verschiedene Kommentarfelder für jeden von euch

Steven A. Lowe
quelle
Danke Steven, das ist die Art von Antwort, die ich mir erhofft hatte. Ich dachte darüber nach, aber ich hoffte, dass es eine alternative Methode für eine solche Aufgabe für Programmierer geben würde (nicht wirklich eine selbst). Danke
gkdsp
@gkdsp: gibt es wahrscheinlich, aber die Chancen stehen gut, dass jeder, der auf das Projekt bietet, ms-word hat
Steven A. Lowe
4
@ Stephen A. Lowe: Als Linux / Mac-Typ hasse ich es, wenn Leute annehmen, dass ich MS-Word habe.
Btilly
@btilly: Die meisten Leute tun es. Wenn Sie keinen philosophischen oder moralischen Grund haben, dies nicht zu tun, sollten Sie dies auch tun. Andernfalls verursachen Sie nur unnötig Probleme für sich selbst und (möglicherweise) andere.
Richard
2
@btilly: mach ein offenes Büro und hör auf zu jammern ;-)
Steven A. Lowe
2

Ich würde einen Programmierer einstellen, der bereits mit Matlab vertraut ist. Rundum weniger Schmerzen für alle. Es gibt viele von uns Ex-Mathematikern, die in der Softwareentwicklung arbeiten :-)

TrojanName
quelle
2
+1: Wenn der Entwickler, den Sie haben, nicht bereit ist, Matlab zu lernen, finden Sie einen besseren Entwickler. Außerdem, wenn er nicht bereit ist, Matlab zu lernen, wie gut kann er die Übersetzung machen?
Kevin Cline
Ich denke definitiv, es wäre viel einfacher, jemanden zu finden, der Matlab bereits kennt, und ihn dazu zu bringen, die 2. Sprache zu lernen, als umgekehrt. (Es sei denn, die 2. Sprache ist noch dunkler und schwer zu lernen! LOL)
TrojanName
1

Whiteboard!

Die Syntax von MATLAB ist im Vergleich zu einer "normalen" prozeduralen Sprache (~ = für nicht gleich !!!!?) Ziemlich weit entfernt, sodass die Dokumentation jeder Codezeile wahrscheinlich nicht allzu hilfreich sein wird (eine einzeilige Matrixtransformation in) MATLAB übersetzt beispielsweise häufig in einige hundert Zeilen C-Code.

Warum verbringen Sie nicht einige Zeit damit, den Kern der Funktionalität des Programms mit dem Entwickler vor einem Whiteboard mit einem Laptop mit (oder Ausdruck) des vorliegenden Codes durchzugehen? Auf diese Weise können Sie sich auf die schwer verständlichen Teile des Programms selbst konzentrieren, nicht auf die MATLAB-Syntax.

Wenn Sie wirklich nur erwarten, dass sie es in eine andere Sprache übersetzen, möchten Sie nicht, dass sie die Vor- und Nachteile der Verarbeitung von MATLAB kennen. Es wird wahrscheinlich nicht sehr gut in andere Sprachen übersetzt, wie MATLAB Sehr spezialisiert auf die Arbeit mit Matrizen. Wirklich müssen sie nur wissen, dass Sie Matrix A mit Produkt B multiplizieren und X mit der Ausgabe machen müssen.

Ed James
quelle
Ich stimme Ed zu. Eine Matlab-Codezeile könnte in einer anderen Sprache noch viel mehr sein. Deshalb halte ich es nicht für ausreichend, einfach das Matlab-Programm bereitzustellen. In Bezug auf Whiteboarding müssen Sie sich in derselben Stadt / demselben Bundesstaat / Land befinden, was normalerweise nicht möglich ist. Außerdem erstelle ich Dokumente, damit Unternehmen für das Projekt bieten können. Ich muss erklären, was sie tun sollen, bevor ich mich für das Team oder die Person entscheide, die das tun soll.
gkdsp
1
Oh Mann. Ich beneide Sie nicht ODER die Firma, die das Angebot gewinnt.
Kevin
Ah, Sie haben den Mangel an physischer Nähe in der Frage nicht bemerkt, also tut mir leid, dass dies keine brillante Passform ist. Ich hatte schon mehrfach die Aufgabe, mit MATLAB zu arbeiten, und meiner Meinung nach wäre der Quellcode praktisch nutzlos, es sei denn, Sie kennen sich mit MATLAB zunächst gut aus und wissen auch genau, was der Code tatsächlich tut . Ich würde definitiv versuchen, eine bildliche Methode zu verwenden, um die Botschaft zu vermitteln, wie Flussdiagramme oder ähnliches. Vielleicht sind ein paar (ich kann nicht glauben, dass ich das vorschlage) UML-Aktivitätsdiagramme angebracht?
Ed James
1
Um ehrlich zu sein, würde ich wahrscheinlich LaTeX wählen und es in ein PDF exportieren, wenn ich eine Menge formatierten Codes, Text und Bilder dazwischen haben würde. Der große Vorteil von LaTeX gegenüber Word ist, dass es tatsächlich gut mit Code umgehen kann (was ich noch nie geschafft habe, Word richtig zu machen).
Ed James
1
whitebord + videorecorder
0

Ich bin eine wissenschaftliche Person, die komplexen Matlab-Code dokumentieren muss, um ihn einem Entwickler zu übergeben, damit er ihn in einer anderen Sprache verstehen und programmieren kann. In der Vergangenheit habe ich MS Word (Erläuterung jedes Programmschritts als neue Zeile in einer Tabelle) und dann Excel verwendet, fand jedoch keine besonders gut geeignet, um meinen Matlab-Code anzuzeigen und Kommentare klar und präzise einzugeben Weg, um es zu dokumentieren.

Nun, Word könnte funktionieren ... Ich denke. Sie definieren verschiedene Stile für verschiedene Teile des Codes (Kommentare in Grün, Code in ...). Ich bin mir jedoch nicht sicher, wie viel dies in der Realität praktikabel ist. Was ist falsch daran, es einfach als HTML zu exportieren und dem fraglichen Entwickler das zu dienen? Er kann jederzeit die Online-Hilfe verwenden, wenn ein Problem vorliegt und MATLAB noch nicht installiert ist.

Lassen Sie mich nach dem Lesen einiger Kommentare versuchen, mehr zu erklären ... Ich gehe davon aus, dass alle Entwickler Pseudocode kennen, aber ich gehe nicht davon aus, dass viele Matlab-Code kennen. Wenn ich also in Pseudocode schreibe, kann ich den Matlab-Code ignorieren (oder ihn als Referenz usw. bereitstellen).

Da Sie MATLAB-Code übersetzen und sagen, dass Sie eine wissenschaftliche Person sind, kann man davon ausgehen, dass mathematische Gleichungen eine praktikable Alternative sein könnten.

Achtung ... manchmal sind die verwendeten MATLAB-Funktionen NICHT die in der Hilfe beschriebenen. Testen Sie Ihren neuen Code unterwegs gründlich.

Turm
quelle