Правила программирования

Этот документ описывает правила, которых нужно придерживаться при программировании роботов в RobomationLAB.

Примечание: скриптовое программирование работает только на Python, а блоки переводятся один к одному в код Python, использующий пакет robomation.

Порядок: сначала общие основные правила (1~2), затем правила блочного кода (3~5) и в конце правила скриптового кода на Python (6~11). И блочный код, и создаваемый код Python одинаково важны.

1. Ограничения перевода блоки ↔ Python

Редактор блочного кода и редактор кода Python соответствуют друг другу один к одному и переводятся в обе стороны в реальном времени.

• Блоки → Python: блоки всегда превращаются в правильный код Python.
• Python → блоки: переводится только код, который можно выразить блоками.

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

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

Чтобы переход в редактор блочного кода работал правильно,
код нужно писать в пределах классов, методов, функций и поддерживаемого синтаксиса, описанных в этом документе и в документах отдельных роботов.

2. Правила подачи кода

Использовать можно только классы, методы и функции, перечисленные в руководстве по API Python robomation и в документе с правилами перевода блоки ↔ Python.
При управлении роботом строго запрещено создавать и использовать новые методы управления роботом, которых нет в этих документах. Исключение — случай, когда пользователь сам просит создать новую функцию.

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

# правильный пример
hamster_s.set_wheel_speed('both', 100)

# неправильный пример - использование функции, которой нет в руководстве по API
hamster_s.set_wheel('both', 100)

# неправильный пример - объявление собственной переменной
SPEED = 100
hamster_s.set_wheel_speed('both', SPEED)

3. Основная структура блочного кода

Подавая блочный код, всегда включайте в основную структуру верхние блоки функций, которые служат точкой входа программы: функция setup и функция loop.
С этим правилом весь блочный код отныне имеет приведённую ниже основную структуру.

Структура блоков (Block Composer)	Как это записывается (текстом)
функция setup	функция setup
(внутренние блоки)	(внутренние блоки)
функция loop	функция loop
(внутренние блоки)	(внутренние блоки)

4. Формат блочного кода (правила переноса строк и отступов)

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

5. Правила записи внутренних блоков и условий

Значение, выбранное в выпадающем списке, или введённое значение — это функциональный аргумент блока, и его записывают в квадратных скобках ([]) ровно в том месте текста блока, где оно находится.
Так текст самого блока и значение, выбранное или введённое пользователем, образуют единое, наглядное целое.

Весь блочный код нужно подавать в виде, содержащем в квадратных скобках ([]) и собственное название блока, и значения, выбранные в выпадающих списках, и введённые пользователем,
воспроизводя текстом настоящий вид блока в Block Composer как можно точнее.

Структура блоков (Block Composer)	Как это записывается (текстом)
если [условие] выполнить [команда] иначе [команда]	если [условие] выполнить [команда] иначе [команда]
RaccoonBot: установить режим управления на [скорость]	RaccoonBot: установить режим управления на [скорость]
RaccoonBot: установить скорость сустава [1]: [100]	RaccoonBot: установить скорость сустава [1]: [100]

6. Основная структура скриптового кода

Подавая скриптовый код (Python), всегда включайте в основную структуру функции setup() и loop(), которые служат точкой входа программы.
Кроме того, в самом верху кода разместите from robomation import *, чтобы можно было пользоваться классами и утилитами для управления роботом, а используемого робота объявите как экземпляр.
С этим правилом весь скриптовый код (Python) отныне имеет приведённую ниже основную структуру.

# основная структура кода Python
from robomation import *

# (если используете робота, объявите его как экземпляр, пример)
hamster_s = HamsterS(0)

# поместите сюда код настройки, выполняемый один раз:
def setup():
    pass

# поместите сюда управляющий код, выполняемый циклически:
def loop():
    pass

7. Формат скриптового кода (правила переноса строк и отступов)

• Функции верхнего уровня (setup, loop и другие) выравнивайте по левому краю.
• Отступ после переноса строки — это всегда одна табуляция (\t). (так же, как отступ в редакторе)

8. Правила управления роботом (экземпляры и методы)

При управлении роботом нужно придерживаться следующих правил.

1. В самом верху кода разместите from robomation import *.
2. Объявите используемого робота как экземпляр. Используйте имя переменной по умолчанию, закреплённое за этим роботом, а индексы задавайте начиная с 0.
3. Управляйте роботом, вызывая методы объявленного экземпляра.

from robomation import *

hamster_s = HamsterS(0)

def setup():
    hamster_s.set_wheel_speed('both', 50)

def loop():
    pass

Используя несколько роботов одного вида, увеличивайте индексы: 0, 1, 2 … (например, hamster_s = HamsterS(0), hamster_s_1 = HamsterS(1))

Установка скорости колёс, движение и подобные команды сами выполняют нужную подготовку (например, отменяют прежние команды движения), поэтому отдельный код инициализации писать не нужно.

9. Правила вызова функций-утилит

Общие утилиты — ожидание времени, воспроизведение звука, запись в журнал, цвета — вызываются через методы класса Utils.

Utils.wait(1)  # (seconds)
Utils.play_sound('', 100, False)
Utils.log(0, '', '')

Полный список функций-утилит смотрите в документах ниже.

• Цвет
• Аудио
• Управление

10. Приоритет собственных методов робота

Управляя оборудованием робота (скоростью колёс, светодиодами, звуком и так далее),
используйте в первую очередь методы экземпляра робота (например, «HamsterS»), а не общие функции-утилиты.

Например, если звук должен издать робот,
вместо функции-утилиты Utils.play_sound() используйте метод sound_clip() экземпляра «HamsterS».

# звук издаёт робот HamsterS. (рекомендуется)
hamster_s.sound_clip('beep')

# звук издаёт компьютер, планшет или телефон. (не рекомендуется)
Utils.play_sound('beep', 100, False)

11. Правила импорта

Когда пишете код на Python, импортируйте только те модули, которые нужны для его выполнения.

• Для управления роботом в самом верху кода обычно размещайте from robomation import *.
• В код, использующий math., автоматически добавляется import math, а в код, использующий random., — import random.
• Кроме того, не импортируйте лишние модули.