程式設計規則
本文檔說明在 RobomationLAB 中進行機器人程式設計時應遵守的程式設計規則。
參考: 脚本程式設計 專用于 Python，積木會 1 對 1 轉換為使用
robomationPython 包的 Python 程式碼。
順序說明: 按共通的核心規則(1~2) → 積木程式碼規則(3~5) → Python 脚本程式碼規則(6~11) 的順序整理。積木程式碼和 Python 程式碼的產生都要作為重點遵守。
1. 積木 ↔ Python 1 對 1 轉換的限制
積木程式設計編輯器和 Python 程式設計編輯器 1 對 1 對應，並實時雙向轉換。
- 積木 → Python: 積木總是會轉換為正確的 Python 程式碼。
- Python → 積木: 只對 能用積木表示的程式碼 進行轉換。
因此，在 Python 編輯器中編寫下面這樣的程式碼時，可能無法從 Python 切換到積木程式設計編輯器，
這時會一起顯示切換失敗的原因。
- 有 Python 語法錯誤的程式碼
- 使用了不與積木對應（轉換規則中未定義）的函式、方法、語法的程式碼
要保持能正常切換到積木程式設計編輯器，
必須在本文檔和各機器人文檔中定義的類、方法、函式以及支援的語法範圍內編寫程式碼。
2. 程式碼提示規則
只能使用 robomation Python API 手冊 和 積木 ↔ 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. 內部積木和條件的表達規則
下拉選單的選擇值或輸入值相當于積木的功能性實參(Argument)，用方括號([])在積木文字中該值所在的位置直接插入來表達。
這樣做是為了把積木固有的文字和使用者選擇、輸入的值結合起來，在視覺上再現積木。
所有積木程式碼都必須以包含積木固有名稱、下拉選單選擇值以及使用者輸入值（全部使用方括號([])）的形式提示，
用文字盡可能貼近地再現實際 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():
pass7. 脚本程式碼的格式（換行和縮進規則）
- 最上層的函式（setup, loop 等）左對齊。
- 換行時產生的縮進必須以 1 個制表符(
\t) 為基准。（與編輯器的縮進基准相同）
8. 機器人控制規則（實例 / 方法）
控制機器人時，必須遵守下面這些規則。
- 在程式碼最上方包含
from robomation import *。 - 把要使用的機器人宣告為實例。變數名使用各機器人既定的預設變數名，索引從 0 開始分配。
- 呼叫所宣告實例的方法來控制機器人。
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. 優先使用機器人專用方法的規則
控制機器人硬體（輪速度、LED、聲音等）時，
必須優先使用機器人（例:「HamsterS」）實例的專用方法，而不是共通的實用函式。
例如，需要用機器人發出聲音時，
必須優先使用「HamsterS」實例的 sound_clip() 方法，而不是實用函式 Utils.play_sound()。
# 透過 HamsterS 機器人發出聲音。(推荐)
hamster_s.sound_clip('beep')
# 透過 PC / 平板 / 移動設備發出聲音。(不推荐)
Utils.play_sound('beep', 100, False)11. Import 規則
編寫 Python 程式碼時，只 import 運行程式碼所需的模組。
- 為了控制機器人，預設在程式碼最上方包含
from robomation import *。 - 使用
math.的程式碼會自動新增import math，使用random.的程式碼會自動新增import random。 - 其他不必要的模組不要 import。