Я приурочил выпуск этого руководства к последнему релизу OpenSCAD[1] и посвятил его этому событию! Последняя версия (2011.12) была выпущена сегодня, так что идите и скачайте её прямо сейчас! Я отметил это руководство как работу в процессе, потому что оно будет нуждаться в обновлении, хотя я не буду обновлять его, за исключением не

Поскольку проекты в OpenSCAD с каждым днем становятся все более сложными, я считаю крайне важным для тех из нас, кто использует его, начать задумываться о последовательном стиле. Макей кода так же важен, как и техническая точность и эффективность, потому что хороший макей обеспечивает читабельный, многократно используемый и поддерживаемый код.

Я хотел бы предложить следующие руководящие принципы стиля в коде OpenSCAD. Если вы не согласны, пожалуйста, выскажитесь или создайте производную версию. Я не ожидаю, что это будет последнее слово по данному вопросу. Моя цель - начать диалог, который, надеюсь, приведет к более удобному для обслуживания коду OpenSCAD.

Пожалуйста, следуйте этим инструкциям как можно точнее, но помните: "Глупое упрямство - это бич мелочных умов"[2][3]. Другими словами, если какое-либо из этих правил приводит к тому, что ваш код становитсяМеньше.Если код не является читабельным и не поддается обслуживанию, вам не следует следовать этому правилу в данных обстоятельствах. Цель всегда заключается в обеспечении читабельности и удобства обслуживания. По крайней мере, выберите один стиль и придерживайтесь его.

Белое пространство.

Вероятно, самым важным фактором для читабельного кода является правильное количество пробелов в нужных местах. В OpenSCAD, как и во многих других языках программирования, пробелы (пустые строки, пробелы и табуляции) игнорируются, что дает нам свободу организовывать код в читабельной и удобной для обслуживания форме.

Отступ

Практически во всех языках рекомендуется (если не является правилом, как в Python), чтобы всякий раз, когда вы начинаете какой-либо блок кода (условие, цикл, модуль), ваш код был отформатирован с отступом (с помощью табуляции или пробелов) на один уровень выше текущего уровня отступа. Пример:

для(z = [-5, 5]) { // разместите открытую фигурную скобку на той же строке
    translate([0, 0, z]) {
        если(z < 0) {
            куб(размер = 0.5, центр = ложный);
        }
Â Â Â Â Â Â Â Â В противном случае, если z > 0, то:
            куб(размер=0.25, центр=ложный);
        }
Â Â Â Â Â Â Â Â В противном случае {
            куб(размер=0.35, центр=ложный);
        }
    } // соответствует открывающему блок символу
} // Для длинных блоков кода используйте здесь комментарий-напоминание (например, // for(z))

Размещение фигурных скобок должно соответствовать стилю читабельности компактного контроля[4]. Это делает код довольно компактным, одновременно облегчая сканирование левого края кода в поисках выровненных операторов управления, таких как if/else. Блоки должны использовать открывающие/закрывающие фигурные скобки во всех случаях (даже в однострочных блоках),

В OpenSCAD отступы всегда должны делаться с помощьюВкладки., а не пробелы, так как в редакторе OpenSCAD для отступов используются табуляции. Однако уместно (и рекомендуется) использовать пробелы для выравнивания констант и операторов, как в этих примерах:

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

Полигон(
    очки = [[0, 0],
              [1, 0], // Одна вкладка, за которой следуют пробелы для выравнивания.
                 [1, 1], // То же самое.
                 [0, 1]],
    пути  = [[0, 1, 2, 3]] // Выровняйте оператор =
);

Здесь стоит отметить, что интервал для выравнивания будет работать только с моношрифтом, поэтому рекомендуется выбрать моношрифт в настройках OpenSCAD.

Одно уникальное правило должно быть установлено для OpenSCAD относительно отступов в блоках кода. Поскольку преобразования и присваивания часто выполняются группами (например, assign(...) scale(...) rotate(...) translate(...) {...]), нет необходимости добавлять отступ для каждого члена группы. В этом случае гораздо чище и понятнее считать всю группу открывателем блока и выров

Assign(x = 5)
scale([1, 1, 0.5])
Вращаем ([180, 0, 0])

Если (y == 0) {
    cube([1, 2, 3]);
)

Это должно быть сделано с помощью операторов присваивания, масштабирования, поворота, перемещения, вычитания, объединения и изменения цвета, но другие блочные операторы должны использоваться только в том случае, если они являются последним элементом в группе. Первые элементы в группе всегда должны быть операторами присваивания, если таковые имеются.

Пространства.

Пробелы удобно использовать для разделения элементов в коде, но важно не переусердствовать. Пробелы после запятых (,) облегчают чтение списков, пробелы вокруг двоеточий (:) упрощают чтение диапазонов, а пробелы вокруг операторов (=, +, -, *, /, %, <, >, <=, >=, ==, !=, !, &&, ||) в целом облегчают ч

Комментарии

Все файлы должны начинаться с блока комментариев (/.../) описывающий вещь, за которым следует блок Thingdoc[5], предоставляющий более формальное определение вещи. A /.../ Блок комментариев перед каждым модулем, описывающий входные параметры, также полезен. Пример:

 Рисует потрясающий объект!
Â
 @param int width Ширина потрясающего объекта, по умолчанию 5
 */
Модуль awesome_object(ширина = 5) {
    .
    .
    .
)

Если у вас есть соблазн прокомментировать код, сначала проверьте, можете ли вы достичь того, что пытаетесь сделать, используя условные операторы или модули и оставив весь код без комментариев. Например, вот это:

// Откомментируйте следующую строку для примера использования!

Можно было бы изменить на это:

Модуль my_awesome_thing_demo(param1, param2) {
    my_awesome_thing(param1, param2);
)

Для сложных блоков кода может быть полезно включать комментарии, описывающие назначение конкретной строки. Если эти комментарии короткие, их можно разместить в конце строки, после открывающего комментарий //, в противном случае их следует разместить на одной или нескольких новых строках выше ссылочного кода (убедившись, что он отступает/выравнивается на уров

Длина строки.

Трудно дать четкое правило относительно длины строк, поскольку (на момент написания этого текста) OpenSCAD не отображает информацию о строках/столбцах. Тем не менее, можно установить общие рекомендации. Всегда следует стараться избегать обернутых строк, потому что они делают код гораздо менее читабельным. Конечно, ширина

1. Модулизируйте код. Если это имеет смысл в вашей ситуации, вы можете переместить код из проблемной строки в модуль или функцию, чтобы сократить эту строку.
2. Разделите строку. Разделите строку на столько строк, сколько необходимо, чтобы все они уместились в одну строку. Разделите.После.Используйте запятые и операторы, а также сочетание табуляций и пробелов, чтобы выравнивать текст по предыдущей строке.

Конвенция именования.

Наименование переменных в OpenSCAD должно соответствовать правиламПодчеркивание имени.Конвенция, соответствующая схеме именования, используемой для встроенных модулей OpenSCAD. Другими словами, переменные должны быть все заглавными с подчёркиваниями для разделения слов. Старайтесь делать имена переменных короткими, уникальными и осмысленными.

Общие руководящие принципы.

Модуляризация.

Вообще говоря, модуль не должен быть длиннее одной страницы. Если у вас есть модуль такой длины, проверьте, можно ли разбить часть кода на отдельные модули, чтобы уменьшить длину модуля. Вы можете с удивлением обнаружить, что часть этого кода можно повторно использовать. Даже если код используется только один раз, выполнение этого действия все же может улуч

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