กฎการเขียนโค้ด

เอกสารนี้อธิบายกฎการเขียนโค้ดที่ต้องปฏิบัติตามเมื่อเขียนโค้ดหุ่นยนต์ใน RobomationLAB

หมายเหตุ: การเขียนโค้ดด้วยสคริปต์ทำงานแบบ Python เท่านั้น และบล็อกจะถูกแปลงแบบหนึ่งต่อหนึ่งเป็นโค้ด 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) 1 ตัว เป็นเกณฑ์เสมอ (เหมือนกับเกณฑ์การเยื้องของตัวแก้ไข)

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. กฎการใช้เมธอดเฉพาะของหุ่นยนต์ก่อน

เมื่อควบคุมฮาร์ดแวร์ของหุ่นยนต์ (ความเร็วล้อ ไฟ LED เสียง ฯลฯ)
ต้องใช้เมธอดเฉพาะของอินสแตนซ์หุ่นยนต์ (เช่น 'HamsterS') ก่อนฟังก์ชันอรรถประโยชน์ร่วม

ตัวอย่างเช่น เมื่อต้องการส่งเสียงด้วยหุ่นยนต์
ต้องใช้เมธอด sound_clip() ของอินสแตนซ์ 'HamsterS' ก่อนฟังก์ชันอรรถประโยชน์ 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 โมดูลที่ไม่จำเป็น