Ich habe die Veröffentlichung dieses Leitfadens so geplant, dass er mit der neuesten Version von OpenSCAD[1] zusammenfällt und diese feiert! Die neueste Version (2011.12) wurde heute veröffentlicht, also geht raus und holt sie euch jetzt! Ich habe dieses Ding als Work in Progress markiert, weil es aktualisiert werden muss, obwohl ich dieses Ding nicht aktualisieren werde, außer für kleinere/grammatikalische Änderungen (

Mit der zunehmenden Komplexität von OpenSCAD-Projekten jeden Tag, denke ich, ist es äußerst wichtig für diejenigen von uns, die es verwenden, über einen konsistenten Stil nachzudenken. Das Layout des Codes ist genauso wichtig wie die technische Genauigkeit und Effizienz, denn ein gutes Layout ermöglicht lesbaren, wiederverwendbaren und wartbaren Code.

Ich möchte die folgenden Richtlinien für den Stil in OpenSCAD-Code vorschlagen. Wenn Sie nicht einverstanden sind, sagen Sie bitte Ihre Meinung oder erstellen Sie eine Derivation. Ich erwarte nicht, dass dies das letzte Wort zu diesem Thema ist. Mein Ziel ist, einen Dialog zu eröffnen, der hoffentlich zu einem besser wartbaren OpenSCAD-Code führen wird.

Bitte folgen Sie diesen Anweisungen so genau wie möglich, aber denken Sie daran: "Eine törichte Konsequenz ist der Kobold kleiner Geister"[2][3]. Mit anderen Worten, wenn eine dieser Regeln dazu führt, dass Ihr CodewenigerWenn es nicht lesbar/wartbar ist, solltest du der Regel in diesem speziellen Fall nicht folgen. Das Ziel ist immer Lesbarkeit und Wartbarkeit. Zumindest solltest du einen Stil wählen und dich daran halten.

Weißer Raum

Der wahrscheinlich wichtigste Faktor für lesbaren Code ist der richtige Abstand an den richtigen Stellen. In OpenSCAD, wie in vielen anderen Programmiersprachen, wird Leerraum (leere Zeilen, Leerzeichen und Tabulatoren) ignoriert, was uns die Freiheit gibt, den Code auf eine lesbare, wartbare Weise anzuordnen.

Einrückung

In praktisch allen Sprachen lautet die Empfehlung (wenn nicht die Regel, wie in Python), dass jedes Mal, wenn Sie einen Codeblock (Bedingung, Schleife, Modul) beginnen, Ihr Code eine Ebene über dem aktuellen Einrückungsniveau eingerückt werden sollte (mit Tabulatoren oder Leerzeichen). Beispiel:

für(z = [-5, 5]) { // Platzieren Sie die öffnende geschwungene Klammer auf derselben Zeile
    translate([0, 0, z]) {
        if(z < 0) {
           cube(Größe = 0.5, Zentrum = falsch);
        }
        sonst, wenn (z > 0) {
            cube(size=0.25, center = false);
        }
        sonst {
            cube(size=0.35, center = false);
        }
    } // stimmt mit dem Block-Öffner überein
} // Für lange Codeblöcke verwenden Sie hier einen Erinnerungskommentar (z. B. // for(z))

Die Platzierung von geschweiften Klammern sollte dem Compact Control Readability Style[4] folgen. Dies macht den Code ziemlich kompakt und erleichtert es, den linken Rand des Codes nach aufgereihten Steueranweisungen wie if/else zu scannen. Blöcke sollten in allen Fällen (auch einzeilige Blöcke) offene/geschlossene geschweifte Klammern verwenden, um Fehler zu vermeiden.

In OpenSCAD sollte die Einrückung immer mit durchgeführt werden.Tabs, keine Leerzeichen, da die Einrückungsabkürzung des OpenSCAD-Editors Tabulatoren verwendet. Es ist jedoch angemessen (und empfohlen), Leerzeichen zu verwenden, um Konstanten und Operatoren wie in diesen Beispielen auszurichten:

vector_of_vectors = [[0, 0, 0],
                             [1, 0, 1],
                             [0, 1, 0]];

Polygon(
    Punkte = [[0, 0],
                 [1, 0], // Ein Tab, gefolgt von Leerzeichen zur Ausrichtung
                 [1, 1], // Gleiches
                 [0, 1]],
    paths  = [[0, 1, 2, 3]] // Richten Sie den =-Operator aus.
);

Hier ist zu beachten, dass der Abstand für die Ausrichtung nur mit einer mono-Schriftart funktioniert, daher wird empfohlen, in den Einstellungen von OpenSCAD eine mono-Schriftart auszuwählen.

Eine einzigartige Regel sollte für OpenSCAD in Bezug auf die Einrückung von Codeblöcken festgelegt werden. Da Transformationen und Zuweisungen häufig in Gruppen auftreten (z. B. assign(...) scale(...) rotate(...) translate(...) {...}), muss man nicht für jedes Mitglied der Gruppe eine Einrückung hinzufügen. Es ist in diesem Fall viel sauberer/lesbarer, die gesamte Gruppe als Blocköffner zu betrachten und sie auf der gle

Assign(x = 5)
scale([1, 1, 0.5])
rotate([180, 0, 0])
translate([5, 5, 0])
wenn (y == 0) {
    cube([1, 2, 3]);
)

Dies sollte mit Zuweisen, Skalieren, Drehen, Übersetzen, Differenzieren, Vereinigen und Farbe erfolgen, aber andere Blockanweisungen sollten nur verwendet werden, wenn sie das letzte Element in der Gruppe sind. Die ersten Elemente in der Gruppe sollten immer "Zuweisen"-Anweisungen sein, falls sie existieren.

Räume

Leerzeichen sind nützlich, um eine gewisse Trennung zwischen Elementen im Code zu schaffen, aber es ist wichtig, nicht zu übertreiben. Leerzeichen nach Kommas (,) erleichtern das Lesen von Listenelementen, Leerzeichen um Doppelpunkte (:) erleichtern das Lesen von Bereichen, und Leerzeichen um Operatoren (=, +, -, *, /, %, <, >, <=, >=, ==, !=, !, &&, ||) erleichtern das

Kommentare

Alle Dateien sollten mit einem Kommentarblock beginnen (/.../) beschreibt das Ding, gefolgt von einem Thingdoc[5]-Block, der eine formellere Definition des Dings liefert. Ein /.../ Ein Kommentarblock vor jedem Modul, der die Eingabeparameter beschreibt, ist ebenfalls nützlich. Ein Beispiel:

/*
 Zeichnet ein fantastisches Objekt!
Â
 @param int width Die Breite des tollen Objekts, standardmäßig 5
 */
Modul awesome_object(Breite = 5) {
    .
    .
    .
)

Wenn Sie versucht sind, Code auszukommentieren, prüfen Sie zunächst, ob Sie das, was Sie versuchen, mit bedingten Anweisungen oder Modulen erreichen können, und lassen Sie den gesamten Code unkommentiert. Zum Beispiel dies:

// Kommentieren Sie die folgende Zeile für eine Beispielverwendung!
//my_awesome_thing(10, 5);

Könnte in das Folgende geändert werden:

Modul my_awesome_thing_demo(param1, param2) {
    my_awesome_thing(param1, param2);
)

Für komplexe Codeblöcke kann es hilfreich sein, Kommentare einzufügen, um den Zweck einer bestimmten Zeile zu beschreiben. Wenn diese Kommentare kurz sind, können sie am Ende der Zeile platziert werden, gefolgt von einem // Kommentar-Öffner, ansonsten sollten sie auf einer oder mehreren neuen Zeilen über dem referenzierten Code platziert werden (wobei sichergestellt werden muss, dass der Code auf der gleichen Ebene wie der referenzierte

Zeilenlänge

Es ist schwierig, eine solide Regel für die Zeilenlänge bereitzustellen, da OpenSCAD (zum Zeitpunkt dieses Schreibens) keine Zeilen-/Spalteninformationen anzeigt. Allerdings können allgemeine Richtlinien festgelegt werden. Man sollte immer versuchen, umgebrochene Zeilen zu vermeiden, da sie den Code viel weniger lesbar machen. Natürlich ist die Breite des Editors für jeden unterschiedlich, also stellen Sie einfach die

1. Modularisieren Sie den Code. Wenn es in Ihrer Situation sinnvoll ist, können Sie Code von der problematischen Zeile in ein Modul oder eine Funktion verschieben, um die Zeile zu verkürzen.
2. Teile die Zeile auf. Teile die Zeile in so viele Zeilen auf, wie nötig, damit sie alle auf einer Zeile passen. TeilenNachKommas und Operatoren und verwenden Sie eine Kombination aus Tabulatoren und Leerzeichen, um mit der vorherigen Zeile aufzurichten.

Benennungskonvention

Die Namensgebung von Variablen in OpenSCAD sollte dem folgen.Unterstrich-BenennungEine Konvention, um dem Namensschema zu entsprechen, das für die integrierten Module von OpenSCAD verwendet wird. Mit anderen Worten, Variablen sollten alle Kleinbuchstaben sein, mit Unterstrichen zur Trennung von Wörtern. Versuchen Sie, Variablennamen kurz, einzigartig und aussagekräftig zu halten.

Allgemeine Richtlinien

Modularisierung

Generell sollte ein Modul nicht länger als eine Seite sein. Wenn Sie ein so langes Modul haben, sollten Sie prüfen, ob Sie einen Teil des Codes in separate Module aufteilen können, um die Länge des Moduls zu reduzieren. Sie werden vielleicht überrascht sein, dass ein Teil dieses Codes wiederverwendbar ist. Selbst wenn der Code nur einmal verwendet wird, kann diese Maßnahme die Lesbarkeit dennoch verbessern.

[1]http://www.openscad.org/
[2]http://www.python.org/dev/peps/pep-0008/
[3]http://www.bartleby.com/100/420.47.html
[4]http://en.wikipedia.org/wiki/Indent_style#Compact_Control_Readability_style
[5]https://github.com/prusajr/ThingDoc/wiki/Syntax