Godot non ha una checklist standard per la code review. Il motore ha una guida di stile, un sistema di avvisi e delle linee guida per la review delle PR per i contributor del motore. Ma se stai costruendo un gioco con un piccolo team o da solo e pubblichi codice su GitHub, non esiste una risorsa canonica del tipo “controlla queste cose prima del merge”.
Questa è quella risorsa.
Ogni controllo qui sotto è basato sulla documentazione ufficiale di Godot 4.6. Dove un controllo fa riferimento a una pagina specifica della documentazione, è collegato. La checklist è organizzata in sei categorie che coprono i problemi più comuni che vediamo nelle pull request di Godot, specialmente nei progetti che usano lo sviluppo assistito dall’IA, dove pattern di versione sbagliata e codice plausibile-ma-rotto compaiono regolarmente.
Usala prima del merge. Stampala. Mettila nel CONTRIBUTING.md del tuo repo. Oppure metti Surmado Code Review sul repo e lascia che Scout controlli automaticamente il diff.
1. Correttezza della versione
Questo codice è davvero scritto per Godot 4?
Questa è la categoria a più alta priorità per qualsiasi progetto che usa assistenza IA. Gli LLM sono addestrati su anni di tutorial, risposte sui forum e documentazione di Godot 3. Produrranno con sicurezza codice Godot 3 in un progetto Godot 4. La guida ufficiale alla migrazione elenca centinaia di rinomine e modifiche non retrocompatibili. Il convertitore di progetto integrato ne intercetta molte, ma la documentazione di Godot stessa avverte che gli script aggiornati probabilmente conterranno ancora errori e gran parte dell’aggiornamento resta manuale.
Anche dopo la migrazione, l’IA può reintrodurre pattern datati in nuovi file. Questa categoria intercetta sia il codice legacy sia il codice generato dall’IA che ha imparato dalla versione sbagliata.
Controllo: i nomi delle classi dei nodi sono tutti aggiornati? Cerca classi rinominate. Le più comuni:
KinematicBody2D→CharacterBody2DKinematicBody→CharacterBody3DPosition2D→Marker2D,Position3D→Marker3DSpatial→Node3DSprite→Sprite2D
L’elenco completo delle rinomine è nella documentazione di migrazione.
Controllo: le firme dei metodi sono aggiornate? Diversi metodi comunemente usati hanno cambiato firma o sono stati rinominati:
move_and_slide()non accetta più argomenti. Legge dalla proprietà integratavelocitydel nodo. (Documentazione 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()
Controllo: le connessioni dei segnali usano la sintassi callable?
Il vecchio pattern connect("signal_name", target, "method_name") è deprecato. Godot 4 usa connessioni basate su callable:
# Vecchio (Godot 3)
button.connect("pressed", self, "_on_button_pressed")
# Attuale (Godot 4)
button.pressed.connect(_on_button_pressed)La forma callable offre validazione a tempo di compilazione. Le connessioni basate su stringhe si rompono silenziosamente a runtime se rinomini il metodo. (Documentazione Signal)
Controllo: le costanti e i nomi dei segnali sono aggiornati?
Le costanti dei colori hanno cambiato formato (ad es. Color.palegreen → Color.PALE_GREEN). Alcuni nomi di segnali sono stati rinominati (ad es. CanvasItem.hide → hidden). Controlla le tabelle di rinomina nella documentazione di migrazione.
2. Callback del ciclo di vita
Il codice viene eseguito nel callback giusto?
Questa è la categoria più pericolosa perché il codice nel callback sbagliato compila, viene eseguito e sembra funzionare. Fallisce in condizioni reali: frame rate diversi, casi limite della fisica o variazioni hardware. La documentazione sulle notifiche di Godot è esplicita su quale callback serve a quale scopo.
Controllo: il movimento fisico è in _physics_process()?
_process() viene eseguito a ogni frame renderizzato e dipende dal frame rate. _physics_process() viene eseguito a una frequenza fissa (60 volte al secondo per impostazione predefinita). Qualsiasi codice che chiama move_and_slide(), move_and_collide(), o manipola direttamente la velocità di un corpo fisico appartiene a _physics_process(). (Introduzione alla fisica)
Controllo: l’input viene gestito nel posto giusto?
Per eventi discreti (pressione di un tasto, click su un pulsante), preferisci _input() o _unhandled_input(). Per lo stato continuo (il tasto è tenuto premuto), _process() o _physics_process() con Input.is_action_pressed() sono appropriati. Fare polling dell’input ogni frame in _process() quando serve solo per il movimento fisico è un pattern comune generato dall’IA.
Controllo: _ready() fa setup, non lavoro continuativo?
_ready() viene eseguito una volta quando il nodo entra nell’albero. I figli eseguono _ready() prima dei genitori. Se l’inizializzazione dipende da un nodo fratello o genitore che deve essere pronto, considera l’uso di await owner.ready o il differimento della chiamata di setup.
3. Igiene dei segnali
I segnali mantengono il codice disaccoppiato?
Il sistema di segnali di Godot permette agli oggetti di reagire agli eventi senza riferirsi direttamente l’uno all’altro. La regola pratica è “chiama verso il basso, segnala verso l’alto”: i nodi genitori possono chiamare metodi sui figli direttamente, ma i figli dovrebbero comunicare verso l’alto tramite segnali. Il codice generato dall’IA viola frequentemente questa regola facendo sì che i figli raggiungano genitori o fratelli.
Controllo: vengono usati segnali invece di riferimenti diretti al genitore?
Se un nodo figlio deve notificare al genitore che qualcosa è accaduto, dovrebbe emettere un segnale. Il genitore si connette a quel segnale. Il figlio non dovrebbe chiamare get_parent().some_method().
Controllo: le connessioni dei segnali sono nel posto giusto?
Il nodo interessato all’evento dovrebbe possedere la connessione. Tipicamente, i nodi genitori si connettono ai segnali dei loro figli in _ready(). Evita di connettere segnali in parti profondamente annidate o distanti dell’albero.
Controllo: i segnali vengono disconnessi quando necessario?
Se i nodi vengono aggiunti e rimossi dinamicamente, connessioni di segnali rimaste attive possono causare errori o comportamenti inaspettati. Controlla se serve una pulizia con disconnect() o queue_free().
4. Architettura della scene tree
Il codice assume una struttura dell’albero fissa?
Godot è costruito attorno a scene componibili che possono essere istanziate ovunque. Percorsi hardcoded e riferimenti al genitore rompono questa componibilità. La documentazione sull’organizzazione delle scene dice che le sotto-scene riutilizzabili dovrebbero funzionare senza richiedere dettagli sul loro ambiente.
Controllo: lo script naviga verso l’alto con ..?
get_node(".."), get_parent() e percorsi come ../../Player sono fragili. Si rompono se la scena viene riassegnata a un altro genitore, riutilizzata in un contesto diverso o ristrutturata. La documentazione sui nodi e le istanze di scena dice che evitare .. è la best practice.
Controllo: dovrebbe essere un riferimento @export invece di un percorso hardcoded?
@export var target: Node ti permette di collegare i riferimenti nell’editor. È più robusto di get_node("../Player") perché sopravvive alla ristrutturazione dell’albero e rende esplicite le dipendenze.
Controllo: dovrebbe usare gruppi invece di riferimenti diretti?
I gruppi ti permettono di taggare i nodi e accedervi senza conoscere il loro percorso. get_tree().get_nodes_in_group("enemies") è più resiliente dell’iterare sui figli per nome.
Controllo: le relazioni genitore-figlio hanno senso? La documentazione dice che le relazioni genitore-figlio dovrebbero rappresentare un vero contenimento: se rimuovere il genitore non dovrebbe rimuovere il figlio, il figlio potrebbe appartenere altrove nell’albero. L’IA spesso annida i nodi per convenienza piuttosto che per correttezza semantica.
5. Sicurezza dei tipi e avvisi
Il progetto usa gli strumenti di sicurezza integrati di Godot?
GDScript supporta la tipizzazione statica e ha un sistema di avvisi integrato. Entrambi sono opzionali ma riducono significativamente le sorprese a runtime. La documentazione dice che i tipi statici aiutano a rilevare errori senza eseguire il codice e migliorano l’autocompletamento dell’editor.
Controllo: i parametri delle funzioni e i tipi di ritorno sono annotati?
# Non tipizzato (funziona ma è rischioso)
func take_damage(amount):
health -= amount
# Tipizzato (intercetta errori durante il parsing)
func take_damage(amount: int) -> void:
health -= amountLa best practice è tutto o niente. La documentazione avverte che mescolare codice tipizzato e non tipizzato nello stesso progetto crea confusione.
Controllo: gli avvisi vengono presi sul serio? Il sistema di avvisi di Godot intercetta variabili inutilizzate, codice irraggiungibile e pattern che possono portare a errori a runtime. Gli avvisi possono essere elevati a errori nelle impostazioni del progetto. Se il tuo progetto ignora tutti gli avvisi, i bug si nascondono.
Controllo: le annotazioni @warning_ignore sono giustificate?
Godot supporta @warning_ignore("unused_variable") e annotazioni simili. Ognuna dovrebbe essere intenzionale, non un modo per silenziare il rumore. Durante la review, chiediti: questo ignore nasconde un problema reale, o è un’eccezione deliberata?
6. Gestione delle risorse
Il codice carica, crea e libera le cose in sicurezza?
Il sistema di risorse di Godot è potente ma ha pattern che l’IA sbaglia spesso, specialmente riguardo al caricamento, all’istanziazione e alla pulizia.
Controllo: la scelta tra load() e preload() è intenzionale?
preload() carica a tempo di compilazione e richiede un percorso stringa costante. load() viene eseguito alla riga in cui è chiamato. Usa preload() per le risorse di cui hai sempre bisogno. Usa load() per le risorse caricate condizionalmente o dinamicamente. L’IA tende a usare load() ovunque perché è più flessibile, ma questo crea caricamento a runtime non necessario.
Controllo: le scene impacchettate vengono istanziate correttamente?
In Godot 4, le scene salvate sono risorse PackedScene. Chiami instantiate() (non instance(), che è il nome di Godot 3) per creare l’albero dei nodi. Controlla che le scene istanziate vengano aggiunte all’albero con add_child().
Controllo: i nodi vengono liberati in sicurezza?
Usa queue_free() a meno che tu non abbia una ragione specifica per non farlo. free() distrugge immediatamente il nodo, e qualsiasi riferimento ad esso diventa istantaneamente nullo. queue_free() aspetta fino alla fine del frame corrente, il che è più sicuro. La documentazione raccomanda queue_free() come impostazione predefinita.
Controllo: gli autoload vengono usati con parsimonia?
Gli autoload sono accessibili globalmente, ma sono comunque nodi nella scene tree. Non devono mai essere rimossi con free() o queue_free() a runtime, altrimenti il motore va in crash. Il codice generato dall’IA a volte tratta gli autoload come gestori usa-e-getta. Verifica se lo stato globale ha davvero bisogno di essere globale o potrebbe essere una risorsa o un gruppo.
Cosa questa checklist non copre
Questa checklist copre la code review: correttezza, architettura e pattern. Non sostituisce:
- Linter e formattatori. Strumenti come
gdscript-toolkite gli avvisi integrati di Godot intercettano sintassi, formattazione, variabili inutilizzate e alcuni problemi di tipo. Usali. Sono complementari. - Il playtesting. La code review intercetta problemi strutturali. Non intercetta “questo non sembra giusto” o “il salto è troppo fluttuante”. Quello è il testing.
- La progettazione dell’architettura. Questa checklist chiede “l’architettura è solida?” Non ti dice quale architettura usare. Per questo, leggi la sezione best practices di Godot.
Automatizzare la checklist
Puoi percorrere questa lista manualmente su ogni PR. Oppure puoi automatizzarla.
Surmado Code Review per Godot controlla ogni push su una pull request GitHub rispetto alla documentazione ufficiale di Godot 4.6, al contesto del tuo repo e al tuo STANDARDS.MD. Intercetta errori di versione, uso improprio del ciclo di vita, pattern deprecati, percorsi fragili nella scene tree e qualsiasi regola personalizzata tu definisca.
Gratis per 10 PR al mese. $15/mese per 100. Nessun prezzo per postazione.
La checklist è cosa rivedere. Surmado Code Review è come rivederlo su ogni PR senza fissare i diff.
Installa Surmado Code Review per Godot (Gratis) →
Non sei sicuro su una specifica API o pattern di Godot? Chiedi a GDScout rispetto alla documentazione ufficiale 4.6. Gratis, con citazioni.
Domande e risposte
Esiste una checklist per la code review di GDScript? Sì. La checklist per la code review di GDScript copre sei categorie: correttezza della versione (pattern Godot 3 vs 4), callback del ciclo di vita (_process vs _physics_process), igiene dei segnali, architettura della scene tree, sicurezza dei tipi e avvisi, e gestione delle risorse. Ogni controllo è basato sulla documentazione ufficiale di Godot 4.6.
Cosa dovrei controllare in una code review di Godot? Una code review di Godot dovrebbe verificare la correttezza della versione (nessun pattern Godot 3 in un progetto Godot 4), l’uso corretto dei callback del ciclo di vita, connessioni di segnali basate su callable, un’architettura della scene tree componibile senza percorsi genitore fragili, la conformità alla tipizzazione statica e agli avvisi, e il caricamento sicuro delle risorse e la pulizia dei nodi. La checklist per la code review di GDScript fornisce controlli specifici per ogni categoria con link alla documentazione ufficiale.
Godot ha uno strumento per la code review? Gli strumenti integrati di Godot includono un sistema di avvisi GDScript e il supporto alla tipizzazione statica, che intercettano errori di sintassi e di tipo. Per la code review a livello di PR, Surmado Code Review per Godot controlla le pull request GitHub rispetto alla documentazione ufficiale di Godot 4.6 e allo STANDARDS.MD di un team. Intercetta errori di versione, uso improprio del ciclo di vita, pattern deprecati e problemi di architettura che i linter non coprono. Gratis per 10 PR al mese.
Quali sono gli errori più comuni nel codice Godot generato dall’IA? Gli errori più comuni sono l’uso di tipi di nodo e firme di metodo Godot 3 rinominati, il posizionamento del movimento fisico in _process() invece che in _physics_process(), l’uso di connessioni di segnali deprecate basate su stringhe, l’hardcoding di percorsi fragili verso nodi genitori e fratelli, e l’uso di load() invece di preload() per risorse a tempo di compilazione. Questi pattern superano il linting e compilano senza errori ma causano fallimenti a runtime o comportamenti incoerenti.
In cosa una checklist per la code review è diversa da un linter GDScript? Un linter GDScript intercetta errori di sintassi, problemi di formattazione, variabili inutilizzate e alcuni problemi di tipo. Una checklist per la code review valuta questioni di livello più alto: è questa la API corretta per la versione del motore, il codice di movimento è nel callback corretto, le connessioni dei segnali sono moderne, l’architettura della scene tree è componibile, e il codice segue gli standard specifici del progetto. Linter e code review sono complementari.
Cos’è STANDARDS.MD? STANDARDS.MD è un documento Markdown che definisce gli standard di codifica che un team applica durante la code review. In Surmado Code Review, STANDARDS.MD viene creato attraverso una conversazione con Scout, l’agente IA di Surmado, piuttosto che modificando un file di configurazione. Il documento può includere regole specifiche per Godot come “usa sempre _physics_process per il movimento di CharacterBody” o “nessuna navigazione con percorso genitore usando get_node(‘..’)”.