O Godot não tem um checklist padrão de code review. O engine tem um guia de estilo, um sistema de avisos e diretrizes de revisão de PR para contribuidores do engine. Mas se você está construindo um jogo com uma equipe pequena ou sozinho e enviando código para o GitHub, não existe um recurso canônico de “verifique isso antes de fazer merge”.
Este é esse recurso.
Cada verificação abaixo é baseada na documentação oficial do Godot 4.6. Onde uma verificação faz referência a uma página específica da documentação, ela está linkada. O checklist está organizado em seis categorias que cobrem os problemas mais comuns que vemos em pull requests do Godot, especialmente em projetos que usam desenvolvimento assistido por IA, onde padrões de versão errada e código plausível-mas-quebrado aparecem regularmente.
Use antes de fazer merge. Imprima. Coloque no CONTRIBUTING.md do seu repositório. Ou coloque o Surmado Code Review no repositório e deixe o Scout verificar o diff automaticamente.
1. Correção de versão
Esse código foi realmente escrito para o Godot 4?
Esta é a categoria de prioridade mais alta para qualquer projeto que usa assistência de IA. LLMs são treinados em anos de tutoriais, respostas de fórum e documentação do Godot 3. Eles vão produzir código do Godot 3 com confiança em um projeto Godot 4. O guia de migração oficial lista centenas de renomeações e mudanças que quebram compatibilidade. O conversor de projeto embutido detecta muitas delas, mas a própria documentação do Godot avisa que scripts atualizados provavelmente ainda vão conter erros e boa parte da atualização permanece manual.
Mesmo depois da migração, a IA pode reintroduzir padrões antigos em novos arquivos. Esta categoria detecta tanto código legado quanto código novo gerado por IA que aprendeu com a versão errada.
Verificação: Todos os nomes de classes de nós estão atuais? Procure por classes renomeadas. As mais comuns:
KinematicBody2D→CharacterBody2DKinematicBody→CharacterBody3DPosition2D→Marker2D,Position3D→Marker3DSpatial→Node3DSprite→Sprite2D
A lista completa de renomeações está na documentação de migração.
Verificação: As assinaturas dos métodos estão atualizadas? Vários métodos usados com frequência mudaram de assinatura ou foram renomeados:
move_and_slide()não recebe mais argumentos. Ele lê a partir da propriedadevelocityembutida do nó. (documentação do CharacterBody2D)instance()→instantiate()set_shader_param()→set_shader_parameter()map_to_world()→map_to_local()(GridMap e TileMap)change_scene()→change_scene_to_file()Thread.start(self, "__method", args)→Thread.start(__method.bind(args))Thread.is_active()→Thread.is_alive()
Verificação: As conexões de sinal usam a sintaxe de callable?
O padrão antigo connect("signal_name", target, "method_name") está obsoleto. O Godot 4 usa conexões baseadas em callable:
# Antigo (Godot 3)
button.connect("pressed", self, "_on_button_pressed")
# Atual (Godot 4)
button.pressed.connect(_on_button_pressed)A forma com callable oferece validação em tempo de compilação. Conexões baseadas em string quebram silenciosamente em tempo de execução se você renomear o método. (documentação de Signal)
Verificação: As constantes e nomes de sinais estão atuais?
As constantes de cor mudaram de formato (por exemplo, Color.palegreen → Color.PALE_GREEN). Alguns nomes de sinal foram renomeados (por exemplo, CanvasItem.hide → hidden). Confira as tabelas de renomeação na documentação de migração.
2. Callbacks de ciclo de vida
O código está rodando no callback certo?
Esta é a categoria mais perigosa porque código no callback errado compila, roda e parece funcionar. Ele falha em condições reais: taxas de quadros diferentes, casos extremos de física ou variação de hardware. A documentação de notificações do Godot é explícita sobre qual callback serve para qual finalidade.
Verificação: O movimento de física está em _physics_process()?
_process() roda a cada quadro renderizado e depende da taxa de quadros. _physics_process() roda em uma taxa fixa (60 vezes por segundo por padrão). Qualquer código que chame move_and_slide(), move_and_collide(), ou manipule diretamente a velocidade de um corpo de física pertence a _physics_process(). (Introdução à física)
Verificação: A entrada é tratada no lugar certo?
Para eventos discretos (tecla pressionada, clique de botão), prefira _input() ou _unhandled_input(). Para estado contínuo (a tecla está sendo mantida pressionada), _process() ou _physics_process() com Input.is_action_pressed() é apropriado. Fazer polling de entrada a cada quadro em _process() quando você só precisa dela para movimento de física é um padrão comum gerado por IA.
Verificação: _ready() está fazendo configuração, não trabalho contínuo?
_ready() roda uma vez quando o nó entra na árvore. Filhos executam _ready() antes dos pais. Se a inicialização depende de um nó irmão ou pai estar pronto, considere usar await owner.ready ou adiar a chamada de configuração.
3. Higiene de sinais
Os sinais estão mantendo o código desacoplado?
O sistema de sinais do Godot permite que objetos reajam a eventos sem se referenciar diretamente uns aos outros. A regra prática é “chame para baixo, sinalize para cima”: nós pais podem chamar métodos nos filhos diretamente, mas os filhos devem se comunicar para cima por meio de sinais. Código gerado por IA frequentemente viola isso fazendo com que filhos acessem pais ou irmãos diretamente.
Verificação: Sinais são usados em vez de referências diretas ao pai?
Se um nó filho precisa notificar o pai de que algo aconteceu, ele deve emitir um sinal. O pai se conecta a esse sinal. O filho não deve chamar get_parent().some_method().
Verificação: As conexões de sinal estão no lugar certo?
O nó que se importa com o evento deve possuir a conexão. Normalmente, nós pais se conectam aos sinais dos filhos em _ready(). Evite conectar sinais em partes profundamente aninhadas ou distantes da árvore.
Verificação: Os sinais são desconectados quando necessário?
Se nós são adicionados e removidos dinamicamente, conexões de sinal remanescentes podem causar erros ou comportamento inesperado. Verifique se é necessário fazer limpeza com disconnect() ou queue_free().
4. Arquitetura da árvore de cena
O código assume uma estrutura de árvore fixa?
O Godot é construído em torno de cenas componíveis que podem ser instanciadas em qualquer lugar. Caminhos fixos e referências ao pai quebram essa componibilidade. A documentação de organização de cena diz que sub-cenas reutilizáveis devem funcionar sem exigir detalhes sobre o ambiente ao redor.
Verificação: O script navega para cima usando ..?
get_node(".."), get_parent() e caminhos como ../../Player são frágeis. Eles quebram se a cena for reparentada, reutilizada em outro contexto ou reestruturada. A documentação de nós e instâncias de cena diz que evitar .. é boa prática.
Verificação: Isso deveria ser uma referência @export em vez de um caminho fixo?
@export var target: Node permite conectar referências no editor. É mais robusto que get_node("../Player") porque sobrevive à reestruturação da árvore e torna as dependências explícitas.
Verificação: Isso deveria usar grupos em vez de referências diretas?
Grupos permitem marcar nós e acessá-los sem conhecer o caminho deles. get_tree().get_nodes_in_group("enemies") é mais resiliente do que iterar pelos filhos por nome.
Verificação: As relações pai-filho fazem sentido? A documentação diz que relações pai-filho devem representar contenção real: se remover o pai não deveria remover o filho, o filho talvez pertença a outro lugar na árvore. A IA frequentemente aninha nós por conveniência, não por correção semântica.
5. Segurança de tipos e avisos
O projeto está usando as ferramentas de segurança embutidas do Godot?
O GDScript suporta tipagem estática e tem um sistema de avisos embutido. Ambos são opcionais, mas reduzem significativamente surpresas em tempo de execução. A documentação diz que tipos estáticos ajudam a detectar erros sem executar o código e melhoram o autocompletar do editor.
Verificação: Os parâmetros de função e tipos de retorno estão anotados?
# Sem tipagem (funciona, mas arriscado)
func take_damage(amount):
health -= amount
# Com tipagem (detecta erros em tempo de parse)
func take_damage(amount: int) -> void:
health -= amountA melhor prática é tudo ou nada. A documentação avisa que misturar código tipado e não tipado no mesmo projeto gera confusão.
Verificação: Os avisos são levados a sério? O sistema de avisos do Godot detecta variáveis não usadas, código inalcançável e padrões que podem levar a erros em tempo de execução. Avisos podem ser escalados para erros nas configurações do projeto. Se seu projeto ignora todos os avisos, bugs se escondem.
Verificação: As anotações @warning_ignore são justificadas?
O Godot suporta @warning_ignore("unused_variable") e anotações similares. Cada uma deve ser intencional, não uma forma de silenciar ruído. Durante a revisão, pergunte: esse ignore está escondendo um problema real, ou é uma exceção deliberada?
6. Gerenciamento de recursos
O código está carregando, criando e liberando coisas com segurança?
O sistema de recursos do Godot é poderoso, mas tem padrões que a IA frequentemente erra, especialmente em torno de carregamento, instanciação e limpeza.
Verificação: load() versus preload() é intencional?
preload() carrega em tempo de compilação e exige um caminho de string constante. load() roda na linha em que é chamado. Use preload() para recursos que você sempre precisa. Use load() para recursos carregados condicionalmente ou dinamicamente. A IA tende a usar load() em todo lugar porque é mais flexível, mas isso cria carregamento desnecessário em tempo de execução.
Verificação: As cenas empacotadas são instanciadas corretamente?
No Godot 4, cenas salvas são recursos PackedScene. Você chama instantiate() (não instance(), que é o nome do Godot 3) para criar a árvore de nós. Verifique se as cenas instanciadas são adicionadas à árvore com add_child().
Verificação: Os nós são liberados com segurança?
Use queue_free() a menos que tenha um motivo específico para não usar. free() destrói o nó imediatamente, e quaisquer referências a ele ficam nulas instantaneamente. queue_free() espera até o fim do quadro atual, o que é mais seguro. A documentação recomenda queue_free() como padrão.
Verificação: Os autoloads são usados com moderação?
Autoloads são acessíveis globalmente, mas ainda são nós na árvore de cena. Eles nunca devem ser removidos com free() ou queue_free() em tempo de execução, ou o engine vai travar. Código gerado por IA às vezes trata autoloads como gerenciadores descartáveis. Avalie se o estado global realmente precisa ser global ou se poderia ser um recurso ou um grupo.
O que este checklist não cobre
Este checklist cobre code review: correção, arquitetura e padrões. Ele não substitui:
- Linters e formatadores. Ferramentas como
gdscript-toolkite os avisos embutidos do Godot detectam sintaxe, formatação, variáveis não usadas e alguns problemas de tipo. Use-as. Elas são complementares. - Playtesting. O code review detecta problemas estruturais. Ele não detecta “isso não parece certo” ou “o pulo está muito flutuante”. Isso é teste.
- Design de arquitetura. Este checklist pergunta “a arquitetura é sólida?”. Ele não diz qual arquitetura usar. Para isso, leia a seção de boas práticas do Godot.
Automatizando o checklist
Você pode passar por essa lista manualmente em cada PR. Ou pode automatizá-la.
O Surmado Code Review para Godot verifica cada push em um pull request do GitHub contra a documentação oficial do Godot 4.6, o contexto do seu repositório e o seu STANDARDS.MD. Ele detecta erros de versão, uso incorreto do ciclo de vida, padrões obsoletos, caminhos frágeis na árvore de cena e quaisquer regras personalizadas que você definir.
Gratuito para 10 PRs por mês. $15/mês para 100. Sem preço por assento.
O checklist é o que revisar. O Surmado Code Review é como revisar isso em cada PR sem ficar encarando diffs.
Instale o Surmado Code Review para Godot (Gratuito) →
Não tem certeza sobre uma API ou padrão específico do Godot? Pergunte ao GDScout com base na documentação oficial da 4.6. Gratuito, com citações.
Perguntas e respostas
Existe um checklist de code review para GDScript? Sim. O Checklist de Code Review para GDScript cobre seis categorias: correção de versão (padrões do Godot 3 versus 4), callbacks de ciclo de vida (_process versus _physics_process), higiene de sinais, arquitetura da árvore de cena, segurança de tipos e avisos, e gerenciamento de recursos. Cada verificação é baseada na documentação oficial do Godot 4.6.
O que devo verificar em um code review do Godot? Um code review do Godot deve verificar a correção de versão (sem padrões do Godot 3 em um projeto Godot 4), o uso correto dos callbacks de ciclo de vida, conexões de sinal baseadas em callable, arquitetura de árvore de cena componível sem caminhos frágeis para o pai, conformidade com tipagem estática e avisos, e carregamento seguro de recursos e limpeza de nós. O Checklist de Code Review para GDScript fornece verificações específicas para cada categoria, com links para a documentação oficial.
O Godot tem uma ferramenta de code review? As ferramentas embutidas do Godot incluem um sistema de avisos de GDScript e suporte a tipagem estática, que detectam erros de sintaxe e de tipo. Para code review no nível de PR, o Surmado Code Review para Godot verifica pull requests do GitHub contra a documentação oficial do Godot 4.6 e o STANDARDS.MD de uma equipe. Ele detecta erros de versão, uso incorreto do ciclo de vida, padrões obsoletos e problemas de arquitetura que linters não cobrem. Gratuito para 10 PRs por mês.
Quais são os erros mais comuns em código do Godot gerado por IA? Os erros mais comuns são usar tipos de nó e assinaturas de método renomeados do Godot 3, colocar movimento de física em _process() em vez de _physics_process(), usar conexões de sinal obsoletas baseadas em string, fixar caminhos frágeis de nós pais e irmãos, e usar load() em vez de preload() para recursos em tempo de compilação. Esses padrões passam pelo linting e compilam sem erros, mas causam falhas em tempo de execução ou comportamento inconsistente.
Como um checklist de code review é diferente de um linter de GDScript? Um linter de GDScript detecta erros de sintaxe, problemas de formatação, variáveis não usadas e alguns problemas de tipo. Um checklist de code review avalia preocupações de nível mais alto: se essa é a API correta para a versão do engine, se o código de movimento está no callback correto, se as conexões de sinal são modernas, se a arquitetura da árvore de cena é componível, e se o código segue os padrões específicos do projeto. Linters e code review são complementares.
O que é o STANDARDS.MD? STANDARDS.MD é um documento em Markdown que define os padrões de código que uma equipe aplica durante o code review. No Surmado Code Review, o STANDARDS.MD é criado por meio de uma conversa com o Scout, o agente de IA da Surmado, em vez de editar um arquivo de configuração. O documento pode incluir regras específicas do Godot, como “sempre use _physics_process para movimento de CharacterBody” ou “sem navegação de caminho para o pai com get_node(‘..’)”.