Anleitung zum Schreiben von Code für Nicht-Programmierer

Hintergrund

Ich habe eine wissenschaftliche Arbeit verfasst, die Code enthält, und vor kurzem die Beweise erhalten, dh was die Schriftsetzer der Zeitschrift aus meinem Manuskript erstellt haben. Das Ergebnis war nicht akzeptabel: Der Einzug ist inkonsistent; am Ende jedes Codeblocks befindet sich ein Punkt; Anführungszeichen wurden zerstört usw. Beachten Sie, dass alle Fehler nicht spezifisch für die von mir verwendete Programmiersprache waren.

Jetzt kann ich sehen, warum jemand, der keine Programmiererfahrung und keine externen Ressourcen hat, solche Fehler machen würde, aber in Zeiten des Internets sollte niemand ohne externe Ressourcen sein. Daher habe ich meine Lieblingssuchmaschine aufgesucht, um nach Vorschlägen zu suchen, und nichts gefunden. Es gibt viele Anleitungen für Programmierer, wie man Code in LaTeX oder ähnlichem formschön schreibt, was alles schön und richtig ist, aber dies ist offensichtlich nicht für den Setzer gedacht, der den Code eines anderen Setzers setzen muss.

Frage

Ich suche eine Ressource, die:

• erklärt die Grundlagen des Satzcodes,
• richtet sich an Schriftsetzer ohne Programmiererfahrung.

Vielleicht ist der eigentliche Punkt, dass Code nicht so gesetzt werden sollte, wie die Leute es verstehen. Wenn Sie Code in ein Dokument einfügen, sollte er wörtlich eingefügt werden , wie in allen Leerzeichen, Tabulatoren, Sonder- oder Nicht-Sonderzeichen und Zeilenumbrüchen.

• Die Tabulatoren sollten 4 oder 8 Leerzeichen breit sein (wobei 4 am häufigsten verwendet werden).
• Die Schriftart sollte eine feste Breite haben. Und fast universell muss es sein.

• Stellen Sie sicher, dass Ihre Anwendung keine Ersetzungen vornimmt!

  Das heißt keine Ligaturen.

  Viele Programme (z. B. Word und InDesign) ändern ihre Anführungszeichen in typografische Paare. Stellen Sie sicher, dass solche Optionen deaktiviert sind, bevor Sie den Code in Ihr Dokument einfügen.

• Lassen Sie den Code nicht automatisch von einer Zeile zur nächsten fließen. Berühren Sie nicht den Code, Sie sind nicht der Experte!

Code ist kein Textkörper, er folgt keinen typografischen Konventionen. Fragen Sie sich, ob Sie Text in eine Illustration eingeben möchten?

Wenn Sie ein Experte sind

Wenn Sie ein Experte sind und die betreffende Sprache kennen, gilt Folgendes.

Hinweis : Nicht raten oder schließen, lesen Sie, was gesagt wurde. Viele Sprachen sehen gleich aus und der Code kann eine Pseudosprache sein, die wie echter Code aussieht. Dann kannst du:

• Gefällt es dem Editor, Keywords genau dann einzufärben / zu fetten / zu kursieren, wenn Ihre Ersetzung dieselbe feste Breite hat? Lassen Sie dies am besten von einem Editor erledigen (Editoren wie beispielsweise scintilla können den formatierten Code exportieren). Denken Sie daran, dass der Herausgeber die Sprache kennen muss, möglicherweise auch Bibliotheken.

  Beachten Sie, dass dies mehr schadet als nützt, wenn Sie es falsch machen.

Wenn Sie ein Domain-Experte sind. Wie Sie die Sprache und Bibliothek kennen und den fraglichen Code verstehen:

• Dann können Sie den Code in mehrere Zeilen neu ausrichten, wenn er nicht zu Ihrem Layout passt. Tun Sie dies nur, wenn Sie wirklich wissen, was Sie tun, und Sie können irreparablen Schaden anrichten.

  Der Lackmustest ist, dass Sie den fraglichen Code geschrieben haben könnten. Wenn nicht, können Sie nicht beurteilen. Fragen Sie den Autor.

  Wie gehe ich damit um? Programmierer verstehen Codestilstandards. Schreiben Sie einfach in die Übermittlungsrichtlinie, dass Sie nur X Zeichen pro Zeile einfügen können. Programmierer können dies dann selbst tun. Code-Editoren haben häufig Werkzeuge dafür. Ein weiterer Grund, eine Mono-Spaced-Schriftart zu verwenden.

Aber dann wusstest du das alles, du warst doch ein Experte. Lassen Sie den Autor den Code besser bearbeiten.

Linien Nummern?

Einige Programmiersprachen und Anwendungsfälle können von Zeilennummern profitieren. Seien Sie hier jedoch vorsichtig, da dies in einigen Sprachen ein Fauxpas ist.

Probleme.

Seien Sie sich bewusst, dass Sie, egal was Sie tun, tatsächlich mit unmöglichen technischen Hürden konfrontiert sein können. Code sollte eigentlich nicht gesetzt sein, sondern nur unformatierter Text. Dies führt zu überraschenden Problemen.

Beispiel: Sprachen wie Python können von vielen PDF-Viewern wie Adobe Acrobat nicht verarbeitet werden. Wenn Sie den Code aus der PDF-Datei einfügen, verzichtet der Editor beim Kopieren und Einfügen darauf, das vorangestellte Leerzeichen einzufügen. Dadurch wird die Möglichkeit zum Einfügen von Code aus PDF in den Editor aufgehoben. Es gibt wirklich keinen guten Weg, damit umzugehen!

Die Antwort mag natürlich von vielen Faktoren abhängen, aber wenn wir mit korrektem, gut formatiertem Klartext-Code beginnen , kann man die Dinge hier mehr oder weniger verallgemeinern.

Die anfängliche 'Formatierung' im Quelltext lautet : Zeilenumbruch , Leerzeichen und Tabulatorzeichen . Beachten Sie, dass die neue Linie und manueller Zeilenumbruch (wie in DTP - Software) ist nicht das Gleiche, und umgekehrt, einige seltenen Sprachen können andere Formatierungszeichen erlauben, obwohl ich noch nie so gehört habe.

Kommentare sind kein ausführbarer Teil des Codes, daher können sie ohne großes Risiko neu formatiert werden, wenn man weiß, ob es sich wirklich um einen Kommentar handelt. Als Erstes sollten Sie sich ansehen, wie Kommentare mit Tags versehen werden.

Einige Grundlagen zur anfänglichen Klartextformatierung sind gut zu wissen. Für Python gibt es beispielsweise den PEP8-Styleguide . Diese Formatierungsanleitung wurde für Python erstellt und kann als Referenz für wichtige Sprachen wie C / C ++ und Java verwendet werden. Die Prüfung verschiedener Beispielprojekte kann im Zweifelsfall hilfreich sein.

Das erste Prinzip wäre also: Ändere nicht den Quelltext. Ich würde eine Checkliste durchgehen - stellen Sie sicher, dass:

• Auf keiner Bühne findet eine automatische Ersetzung von Zeichen statt .
• Es werden keine Änderungen am Text vorgenommen (es sei denn, Sie sind zu 100% sicher, dass diese vorgenommen werden müssen).
• Es werden keine Zeilenumbrüche angezeigt.
• Einrückungen bleiben optisch erhalten und sind konsistent (ca. 4 x  Breite pro Einrückungsebene).
• Die anfängliche Einrückungsstufe (Null) sollte sichtbar sein.
• Definierte Stile zerstören die Formatierung der Syntax nicht (wenn Syntaxhervorhebung verwendet wird).
• Erstellen Sie eine Sicherungskopie der Quelle im Nur-Text-Format, um die ursprüngliche Formatierung erneut zu überprüfen oder neu zu starten.
• Zeilennummern sollten, falls vorhanden, intakt sein, insbesondere wenn sie in Erklärungen angegeben sind.

Wenn die Originalquelle richtig formatiert ist, sollte es überhaupt keinen Zeilenumbruch geben. Wenn immer noch umbrochene Linien angezeigt werden und nicht zu vermeiden sind, ist ein einstufiger hängender Einzug die häufigste Lösung (siehe oben verknüpftes PEP). Wenn ein Zeilenumbruch erforderlich ist, wenden Sie sich an den Styleguide oder den Autor.

Einige kleinere Leerzeichen müssen möglicherweise ersetzt werden. Da kann die Quelle Tab - Zeichen enthält, das bedeutet natürlich , dass der Setzer muß sicherstellen , dass alle Tabs am Anfang jeder Zeile konsistent sind, dh verschachtelte Vertiefungen visuell erhalten sind und jede nächste Stufe der Vertiefung ist von gleicher Breite (ca. vier x  Breiten pro Einrückungsebene).

Idealerweise sollten die Einrückungen, die mit Leerzeichen oder gemischten Leerzeichen und Tabulatoren erstellt wurden, durch Tabulatoren ersetzt werden (oder durch das, was die DTP-Software für verschachtelte Einrückungen besser kann), sodass das Anpassen der Einrückungen bei Bedarf möglicherweise einfacher ist.
Natürlich kann man Leerzeichen lassen, aber es kann schwieriger sein, ihre Breite zu verwalten, wenn die Schriftart geändert wird, und es kann schwieriger sein, Einrückungen innerhalb der Zeilen wie in Tabellenspalten auszurichten.

Monospaced Schriftart + Leerzeichen

Beachten Sie, dass, wenn die Quelle absichtlich mit Leerzeichen formatiert wurde und nur in monospaced Schrift gelesen werden sollte (z. B. ASCII-Diagramme oder ASCII-Grafiken), die Leerzeichen vollständig unverändert bleiben sollten , diese Entscheidung jedoch von Anfang an getroffen werden sollte. In diesem Fall ist die Schriftart "Courier New" am gebräuchlichsten. Auch wenn dies nicht wirklich benötigt wird, rate ich von monospaced ab, da immer weniger neue Leute heutzutage monospaced für das Codieren wählen und im Falle des Korrekturlesens proportionale Schriftarten ein besseres Leseerlebnis bieten.

Im Allgemeinen funktionieren komprimierte (z. B. Arial-Narrow) oder kleinere Schriftarten möglicherweise besser: Sie werden im Gegensatz zu Fließtext stärker hervorgehoben, der Code wird kompakter, und es ist weniger wahrscheinlich, dass unerwünschte Zeilenumbrüche auftreten.

Ich denke, hier kann man eine Linie zeichnen, und wenn das oben Gesagte getan wird, dann besteht eine Wahrscheinlichkeit von 99%, dass alles in Ordnung ist, zumindest für einen einfachen Codeblock mit einer Schriftart ohne Farben.

Tools und erweiterte Formatierung

Darüber hinaus kann das Erscheinungsbild mithilfe der Syntaxhervorhebung erheblich verbessert werden.

• Farbdruck oder Bildschirmanzeige: In einem vollfarbigen Layout kann jede Hervorhebungsfunktion verwendet werden. Dies ist also der beste Fall, aber beim Drucken können sich einige Farbänderungen ergeben.

• Graustufen- oder S / W-Druck: Hier kann natürlich Fettdruck (z. B. Stichwörter) oder Kursivdruck (z. B. Kommentare) verwendet werden. Beachten Sie jedoch, dass Farben mit allen Konsequenzen in Grau umgewandelt werden. Beispielsweise können abgeblendete Kommentare auf einem Display gut aussehen, auf Papier jedoch zu blass werden.

Die wichtigste Frage ist, ob der Layouter über Tools verfügt, die den Code in lesbarer Form darstellen können. Glücklicherweise gibt es viele kostenlose Tools für die Codebearbeitung . Die bekanntesten (für Windows) sind: Notepad ++, VSCode, Visual Studio . Beachten Sie jedoch mögliche implizite automatische Konvertierungen von Tabulatoren in Leerzeichen.

In Notepad ++ gibt es eine Option zum Exportieren des Codes als RTF , wodurch alle Formatierungen und Syntaxhervorhebungen der Quelle beibehalten werden.

Wenn das Layout keine Änderung des Textflusses in der Codedarstellung erfordert, kann man Bilder (Screenshots) direkt verwenden - es ist nicht so flexibel wie Text, behält aber 100% Formatierung und Zeilennummerierung bei und kann viel Zeit sparen. ZB kann es schwierig sein, Zeilennummern in Textform zu speichern. Auch das Exportieren in PDF ist eine gute Alternative - aber nicht alle DTP-Programme können PDFs einbetten, und beim Drucken in PDF können einige Formatierungen verloren gehen.

Zum Beispiel sieht mein Setup für Python-Code in Notepad ++ so aus:

Dies soll nur veranschaulichen, dass man Screenshots direkt verwenden kann und dies möglicherweise die einfachste Methode ist. Es gibt verschiedene Tools, die bei der Bildschirmaufnahme helfen können. Möglicherweise müssen die Bildschirme für Bilder mit höherer Auflösung zusammengefügt werden.

Das Farbschema wird natürlich individuell im Stilkonfigurator des Editors festgelegt, der die unterstützte Sprache bereits kennt, was es schwierig macht, falsche Formatierungen vorzunehmen, selbst wenn man die Syntax nicht kennt. Hier sollten allgemeine Typografieregeln gelten: Nicht zu viele Farben, konsistente Schriftarten, Einrückungen, angenehmer Zeilenabstand.

Zusätzliche Tools / Plugins für benutzerdefinierte Sprachdefinitionen sind ebenfalls üblich, erfordern jedoch Syntaxkenntnisse.

In HTML gibt es ein Tagset <code> ... </ code>, das den Leser / Interpreter anweist, den Inhalt absolut wörtlich zu behandeln. Auch <pre> ... </ pre> macht so ziemlich dasselbe. Als jemand, der häufig Formeln, Gleichungen und Code für die Veröffentlichung setzen musste, empfehle ich auch die Verwendung von BILDERN, um dies zu tun ... mache ein GIF oder JPG oder PNG des problematischen Elements.

Ein weiterer Faktor ist, dass Code traditionell in Courier-Monospace- oder anderen Monospace-Schriftarten gerendert wird, da Semaphoren oder Telegraphen für den Leser bedeuten, dass es sich nicht um Textkörper handelt. Ich unterschreibe diese Stilwahl, ich denke, es macht sehr viel Sinn.

In den meisten "Legacy" -Satzsystemen waren mathematische Gleichungen von relativ hoher Komplexität äußerst zeitaufwändig und voller Fehler.