¡Programé el lanzamiento de esta guía para que coincidiera con y conmemorara el último lanzamiento de OpenSCAD[1]! La última versión (2011.12) se lanzó hoy, así que sal y consíguela ahora! He marcado esto como un trabajo en progreso porque necesitará actualizaciones, aunque no actualizaré esto, excepto cambios menores/gramaticales (cualquier actualización debería hacerse en forma de un derivado, para que cualquiera pueda hacer

Con los proyectos de OpenSCAD aumentando en complejidad cada día, creo que es extremadamente importante para aquellos de nosotros que lo usamos comenzar a pensar en un estilo consistente. El diseño del código es tan importante como la precisión técnica y la eficiencia, porque un buen diseño permite un código legible, reutilizable y mantenible.

Me gustaría proponer las siguientes directrices de estilo para el código de OpenSCAD. Si no estás de acuerdo, por favor, expresa tu opinión o crea una derivación. No espero que esto sea la última palabra sobre el tema. Mi objetivo es abrir un diálogo que, con suerte, resulte en un código de OpenSCAD más fácil de mantener.

Por favor, siga estas instrucciones lo más de cerca que pueda, pero recuerde: "Una consistencia tonta es el duende de las mentes pequeñas"[2][3]. En otras palabras, si alguna de estas reglas hace que tu código seamenosSi no es legible o mantenible, no deberías seguir la regla en esa circunstancia particular. El objetivo siempre es la legibilidad y la mantenibilidad. Por lo menos, elige un estilo y manténte fiel a él.

Espacio en blanco.

Probablemente, el factor más importante para un código legible es la cantidad adecuada de espacio en los lugares correctos. En OpenSCAD, al igual que en muchos otros lenguajes de programación, se ignora el espacio en blanco (líneas vacías, espacios y tabuladores), lo que nos da la libertad de organizar el código de una manera legible y mantenible.

Indentación.

En prácticamente todos los lenguajes, la sugerencia (si no la regla, como en Python) es que cada vez que comiences algún tipo de bloque de código (condicional, bucle, módulo), tu código debería indentarse (con tabuladores o espacios) un nivel por encima del nivel de indentación actual. Ejemplo:

para(z = [-5, 5]) { // coloca la llave curva de apertura en la misma línea
    translate([0, 0, z]) {
        si(z < 0) {
            cubo(tamaño = 0.5, centro = falso);
        }
        De lo contrario, si (z > 0) {
            cubo(tamaño=0.25, centro = falso);
        }
        else {
            cubo(tamaño=0.35, centro = falso);
        }
    } // se alinea con el iniciador de bloque
} // Para bloques de código largos, use un comentario recordatorio aquí (por ejemplo, // for(z))

La colocación de los corchetes debe seguir el Estilo de Legibilidad de Control Compacto [4]. Esto hace que el código sea bastante compacto al tiempo que facilita escanear el borde izquierdo del código en busca de declaraciones de control alineadas como if/else. Los bloques deben usar corchetes abiertos/cerrados en todos los casos (incluso en bloques de una sola línea) para evitar errores.

En OpenSCAD, la indentación siempre se debe hacer conPestañas, no espacios, ya que el atajo de sangría del editor de OpenSCAD utiliza tabuladores. Sin embargo, es apropiado (y se recomienda) usar espacios para alinear constantes y operadores como en estos ejemplos:

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

Polígono(
    puntos = [[0, 0],
                 [1, 0], // Una pestaña, seguida de espacios para la alineación.
                 [1, 1], // Lo mismo.
                 [0, 1]],
    paths  = [[0, 1, 2, 3]] // Alinee el operador =
);

Algo que hay que tener en cuenta aquí es que el espaciado para la alineación solo funcionará con una fuente mono, por lo que se recomienda elegir una fuente mono en las preferencias de OpenSCAD.

Una regla única debería establecerse para OpenSCAD con respecto a la indentación de bloques de código. Dado que las transformaciones y asignaciones a menudo vienen en grupos (por ejemplo, asignar(...) escalar(...) rotar(...) traducir(...) {...}), no es necesario agregar indentación para cada miembro del grupo. Es mucho más limpio/legible en este caso pensar en todo el grupo como el abridor de bloque y alinearlos al mismo nivel de indent

asignar(x = 5)
escala([1, 1, 0.5])
Rotar([180, 0, 0])
traducir([5, 5, 0])
si(y == 0) {
    cube([1, 2, 3]);
}

Esto debería hacerse con asignar, escalar, rotar, traducir, diferencia, unión y color, pero otras declaraciones de bloque solo deberían usarse si son el último elemento del grupo. Los primeros elementos del grupo siempre deberían ser declaraciones de "asignar" si existen.

Espacios.

Los espacios son útiles para proporcionar cierta separación entre los elementos del código, pero es importante no exagerar. Los espacios después de las comas (,) hacen que sea fácil leer los elementos de la lista, los espacios alrededor de los corchetes (:) hacen que sea más fácil leer los rangos, y los espacios alrededor de los operadores (=, +, -, *, /, %, <, >, <=, >=

Comentarios.

Todos los archivos deben comenzar con un bloque de comentarios (/.../) describiendo la cosa, seguido de un bloque Thingdoc[5] que proporciona una definición más formal de la cosa. A /.../ Un bloque de comentarios antes de cada módulo que describa los parámetros de entrada también es útil. Un ejemplo:

/*
 ¡Dibuja un objeto increíble!
Â
 @param int width El ancho del objeto increíble, por defecto es 5
 */
Módulo awesome_object(anchura = 5) {
    .
    .
    .
}

Si te sientes tentado a comentar el código, primero ve si puedes lograr lo que estás intentando usando declaraciones condicionales o módulos y dejando todo el código sin comentar. Por ejemplo, esto:

//my_awesome_thing(10, 5);

Podría cambiarse a esto:

Módulo my_awesome_thing_demo(param1, param2) {
    my_awesome_thing(param1, param2);
}

Para bloques de código complejos, puede ser útil incluir comentarios para describir el propósito de una línea en particular. Si estos comentarios son cortos, pueden colocarse al final de la línea, siguiendo un abridor de comentario //, de lo contrario, deben colocarse en una o más líneas nuevas por encima del código referenciado (asegurándose de indentar/alinear al nivel del código referenciado antes de comenzar el coment

Longitud de la línea.

Es difícil proporcionar una regla sólida para la longitud de la línea ya que (al momento de escribir esto) OpenSCAD no muestra información de línea/columna. Sin embargo, aún se pueden establecer pautas generales. Siempre se debe tratar de evitar las líneas envueltas, ya que hacen que el código sea mucho menos legible. Por supuesto, el ancho del editor es diferente para todos, así que simplemente configure el ancho de

1. Modularizar el código. Si tiene sentido en tu situación, puedes mover el código de la línea ofensiva a un módulo o función para acortar la línea.
2. Divide la línea. Divide la línea en tantas líneas como sea necesario, donde todas cabrán en una sola línea. Divide.Después deUsar comas y operadores, y emplear una combinación de tabuladores y espacios para alinear con la línea anterior.

Convención de nomenclatura.

El nombramiento de variables en OpenSCAD debe seguir las reglas deunderscore_namingConvención para coincidir con el esquema de nomenclatura utilizado para los módulos integrados de OpenSCAD. En otras palabras, las variables deben estar todas en minúsculas con guiones para separar las palabras. Intente mantener los nombres de las variables cortos, únicos y significativos.

Directrices generales

Modularización.

En general, un módulo no debería tener más de una página de longitud. Si tienes un módulo tan largo, ve si puedes dividir parte del código en módulos separados para reducir la longitud del módulo. Puede que te sorprendas al descubrir que parte de este código es reutilizable. Incluso si el código solo se usa una vez, tomar esta acción aún puede mejorar la legibilidad.

[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]