Anleitung zum Schreiben von Code für Nicht-Programmierer

13

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.
Wrzlprmft
quelle
Die Schwierigkeit dabei ist, dass es von der Sprache und den verwendeten Konventionen abhängt. Die Frage ist also ziemlich weit gefasst, auch wenn die Antworten nur eine Ressource verknüpfen
Zach Saucier,
2
@Scott Nun, in Bezug auf Anführungszeichen, Leerzeichen, Zeichen - in der Tat kann man ziemlich gut verallgemeinern: Sie müssen erhalten bleiben.
Mikhail V
1
@MikhailV Ich habe nur das Gefühl, dass viele Codesprachen mehr mit Fremdsprachen gemeinsam haben als nur Richtlinien. Sicher können Sie grob festlegen, wo Leerzeichen und Zeilenumbrüche platziert werden sollen. Um jedoch genau zu sein, müssen Sie die Sprache, in der Sie Korrektur lesen, wirklich verstehen. Ja, Sie können den Redakteuren / Korrektoren sagen, sie sollen "so wie sie sind" lassen, was jedoch nicht bedeutet, dass dies letztendlich korrekt ist.
Scott
1
@Wrzlprmft Lustige Sache, man kann Python Form PDF nicht kopieren, ohne alle vorangegangenen Leerzeichen in Acrobat oder Acrobat Reader zu verlieren. Sie werden "intelligent" entfernt. Wenn Sie Code in viele WYSIWYG-Editoren wie word oder INdesign einfügen, werden die Anführungszeichen durch typografische Anführungszeichen ersetzt (es sei denn, Sie deaktivieren eine solche Funktion), aber für Code, der tatsächlich BAD ist. Auch in idesign können Sie Code nicht richtig eingeben, ohne ein anderes Zeichen für den Zeilenumbruch einzufügen. Dies kann durchaus zu einer schlechten Sache werden, wenn Sie den Code jemals zurückkopieren.
joojaa
1
@ usr2564301: Erstens wird diese Frage jetzt von einigen Suchmaschinen gefunden, und daher ist es wahrscheinlicher, dass jeder Schriftsetzer, der die gleichen Probleme wie ich hat, eine mögliche Antwort findet (und wenn nicht, könnte ich selbstgefällig sein) darüber). Zweitens, ja, ich würde einen Link in die Antwort auf meine Proofs aufnehmen, da dies noch nicht begangene Fehler in der zweiten Proofrunde verhindern kann. Es tut auch nicht weh, eine Referenz zu haben, wenn der Schriftsetzer hartnäckig ist. Schließlich ist dies ein Journal / Verlag, der sich selten mit Code auseinandersetzen muss, weshalb er sich etwas von den von Ihnen dargestellten Szenarien unterscheidet.
Wrzlprmft

Antworten:

7

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!

joojaa
quelle
@ usr2564301 ah ja so wahr
joojaa
1
@ usr2564301 Fertig, trotzdem denke ich, dass eine lesbare Schriftauswahl etwas ist, das ein Typograf verstehen sollte. Wie auch immer, eine, die auch ein i ohne Punkt in Kleinbuchstaben unterscheidet (ja, wir haben einen Code für einen Monat getestet, weil wir nicht wussten, dass ein 'i' in Kleinbuchstaben von einem 'i' in Großbuchstaben in einem türkischen Gebietsschema verschieden ist), bildet eine 1 Auch
joojaa
"Lassen Sie den Code nicht von einer Zeile zur nächsten fließen", ist theoretisch ein guter Ratschlag. Wenn Sie jedoch für ein Standard-6x9-Druckformat schreiben und eine Codezeile mit 600 Zeichen haben, müssen Sie sich nur schwer daran halten.
Janus Bahs Jacquet
1
@JanusBahsJacquet Code wird normalerweise mit weniger als 80 Zeichen pro Zeile geschrieben. Wenn du so etwas bekommst, sind deine Einreichungsrichtlinien vielleicht schlecht. Programmierer kennen die Richtlinien für das Einreichen, schließlich sind das Codebasen. Wenn Sie die Zeilen durchbrechen, können Sie die Bedeutung des Codes ändern.
Joojaa
1
@JanusBahsJacquet Wenn Sie den Autor darum bitten, aktualisieren Sie die Richtlinien, damit Sie dies nicht zu oft tun müssen. Nun, in beiden Fällen, wenn der Code nicht in lange Zeilen aufgeteilt werden kann, kann der Schriftsetzer auch nichts dagegen tun. Übrigens, was würde ein Schriftsetzer mit einem zu breiten Bild machen, das nicht in der Größe verändert oder beschnitten werden kann? Wie auch immer, ich werde vorhersagen, dass Code-Einsendungen in Zukunft häufiger vorkommen werden
am
4

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:
Bildbeschreibung hier eingeben

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.

Mikhail V
quelle
Dies ist eine wunderbare und sorgfältig durchdachte Antwort. Screenshots können jedoch aufgrund der Auflösung suboptimal sein, wenn Sie vorhaben, diese auszudrucken. Etwas zu beachten.
Jeremy Carlson
1
@JeremyCarlson In Np ++ kann auch die Schriftgröße / der Zeilenabstand angepasst werden. Theoretisch gibt es also keine Begrenzung für die Auflösung von Screenshots, aber es wird schwieriger, sie zu erstellen, insbesondere auf einem kleinen Display. Es kann sogar einen Trick geben, die virtuelle Anzeige zu verwenden und eine sehr große Fenstergröße einzustellen
Mikhail V
weil immer weniger neue Leute heute monospaced für die Codierung wählen - Das mag sein, aber monospaced wird immer noch von der großen Mehrheit verwendet. Sie können normale Satzkonventionen nicht einfach in Code übersetzen. Beispielsweise sind Interpunktionszeichen wichtiger als in normalen Texten (die meisten Argumente aus meiner Antwort übersetzen dies). Eine Nicht-Monospace-Codeschrift unterscheidet sich erheblich von einer für normalen Text. Außerdem möchten Sie häufig, dass bestimmte ähnliche Strukturen horizontal ausgerichtet sind, z . B. a[i][j] = 1a[m][n] = 2.
Wrzlprmft
@Wrzlprmft danke für die bearbeitungen. Und ja, es gibt nicht so viele gute Schriftarten, die für Code und Mathematik optimiert sind (Verdana ist in Ordnung). In der Tat hat Times winzigen Punkt und Doppelpunkt und einige andere Probleme, aber ich benutze es den ganzen Weg - "die Vorteile überwiegen die Kosten"
Mikhail V
-5

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.

Dwoz
quelle
Natürlich können Bilder nicht ausgeschnitten und eingefügt werden!
Dwoz
3
Ich verstehe nicht, wie dies die Frage beantwortet, die überhaupt gestellt wird
Zach Saucier