Objetivo da aula

• Aprender a escrever códigos claros, organizados e de fácil compreensão.
• Entender a importância da indentação e da padronização no Python.
• Conhecer boas práticas para trabalhar com o PyBricks em competições da FLL.
• Evitar erros comuns que dificultam a leitura e o funcionamento dos programas.

Por que as boas práticas são importantes?

Em competições como a FIRST LEGO League, a equipe precisa trabalhar de forma colaborativa.
Ter códigos bem escritos e padronizados facilita que todos entendam o que cada parte faz, permitindo ajustes rápidos durante os treinos e torneios.

Além disso, o Python é uma linguagem que valoriza a clareza e a organização.
Mesmo pequenos erros de espaço ou digitação podem impedir o programa de funcionar.
Por isso, seguir boas práticas é fundamental desde o início.

1. Use indentação corretamente

No Python, os espaços no início de cada linha (chamados de indentação) definem quais comandos pertencem a um mesmo bloco de código.
Cada bloco deve ter o mesmo nível de recuo, geralmente com 4 espaços por nível.

for i in range(3):
    motorA.run_angle(300, 360)
    wait(500)
hub.speaker.beep()

Observe que as duas linhas dentro do for estão recuadas.
Isso mostra ao Python que elas fazem parte do mesmo laço de repetição.

2. Use nomes claros para variáveis e objetos

Evite nomes genéricos como x, y ou a.
Prefira nomes que expliquem o que a variável representa.

# Exemplo ruim
m = Motor(Port.A)
m.run_angle(300, 360)

# Exemplo bom
motor_garra = Motor(Port.A)
motor_garra.run_angle(300, 360)

Bons nomes tornam o código mais fácil de ler e entender, tanto para você quanto para seus colegas de equipe.

3. Comente seu código

Os comentários ajudam a explicar o que o programa faz, especialmente em partes mais complexas.
No Python, um comentário começa com o símbolo # e é ignorado na execução.

# Inicia o hub e define o motor da garra
hub = PrimeHub()
motor_garra = Motor(Port.A)

# Abre a garra
motor_garra.run_angle(300, 90)

# Fecha a garra
motor_garra.run_angle(300, -90)

Use comentários para descrever a intenção do código, e não apenas repetir o que já está claro.

4. Organize seu código em seções

Sempre que possível, separe o código em blocos lógicos com espaços entre eles.
Isso facilita a leitura e a depuração (identificação de erros).

# Importações
from pybricks.hubs import PrimeHub
from pybricks.pupdevices import Motor
from pybricks.parameters import Port
from pybricks.tools import wait

# Inicializações
hub = PrimeHub()
motor_esquerdo = Motor(Port.A)
motor_direito = Motor(Port.B)

# Execução
motor_esquerdo.run_angle(300, 360)
motor_direito.run_angle(300, 360)

5. Use funções quando possível

As funções ajudam a evitar repetição e tornam o código mais organizado.
Elas são criadas com a palavra def e podem ser reutilizadas várias vezes.

def andar_para_frente():
    motor_esquerdo.run_angle(300, 360)
    motor_direito.run_angle(300, 360)

# Chama a função
andar_para_frente()

Em projetos maiores, as funções ajudam a dividir o código em partes menores, mais fáceis de entender e ajustar.

6. Salve e nomeie bem seus arquivos

Sempre salve o arquivo com um nome que indique o que ele faz.
Evite nomes genéricos como test.py ou programa1.py.

Exemplos de bons nomes:

• giro_motor_garra.py
• seguir_linha_basico.py
• mover_para_missao1.py

7. Teste e ajuste continuamente

Nenhum código nasce perfeito.
Teste uma parte de cada vez, observe o comportamento do robô e ajuste os valores até atingir o resultado desejado.

Fazer pequenos testes ajuda a identificar erros mais rapidamente e evita perder tempo procurando problemas em programas longos.

Atividade prática

1. Abra o editor PyBricks e crie um novo arquivo com o nome motor_treino.py.
2. Copie um dos exemplos anteriores e adicione comentários explicando o que cada linha faz.
3. Adicione uma função chamada mover_duas_voltas() que faça o motor girar duas vezes.
4. Teste e ajuste até que o movimento aconteça como esperado.

Na próxima aula, vamos avançar para o Módulo 2, aprendendo a trabalhar com variáveis, repetições e decisões para deixar o robô ainda mais inteligente.