Godot no tiene un checklist estándar de revisión de código. El motor tiene una guía de estilo, un sistema de advertencias y pautas de revisión de PR para colaboradores del motor. Pero si estás construyendo un juego con un equipo pequeño o en solitario y subiendo código a GitHub, no hay un recurso canónico de “revisa estas cosas antes de hacer merge”.
Este es ese recurso.
Cada verificación de abajo está basada en la documentación oficial de Godot 4.6. Donde una verificación hace referencia a una página específica de la documentación, está enlazada. El checklist está organizado en seis categorías que cubren los problemas más comunes que vemos en pull requests de Godot, especialmente en proyectos que usan desarrollo asistido por IA, donde los patrones de versión incorrecta y el código plausible pero roto aparecen con regularidad.
Úsalo antes de hacer merge. Imprímelo. Ponlo en el CONTRIBUTING.md de tu repo. O pon Surmado Code Review en el repo y deja que Scout revise el diff automáticamente.
1. Corrección de versión
¿Este código realmente está escrito para Godot 4?
Esta es la categoría de mayor prioridad para cualquier proyecto que use asistencia de IA. Los LLM están entrenados con años de tutoriales, respuestas de foros y documentación de Godot 3. Producirán código de Godot 3 con total confianza en un proyecto de Godot 4. La guía de migración oficial lista cientos de renombramientos y cambios que rompen compatibilidad. El conversor de proyectos integrado detecta muchos de ellos, pero la propia documentación de Godot advierte que los scripts actualizados probablemente aún contendrán errores y que gran parte de la actualización sigue siendo manual.
Incluso después de la migración, la IA puede reintroducir patrones antiguos en archivos nuevos. Esta categoría detecta tanto el código heredado como el código nuevo generado por IA que aprendió de la versión equivocada.
Verificación: ¿Todos los nombres de clases de nodos están actualizados? Busca clases renombradas. Las más comunes:
KinematicBody2D→CharacterBody2DKinematicBody→CharacterBody3DPosition2D→Marker2D,Position3D→Marker3DSpatial→Node3DSprite→Sprite2D
La lista completa de renombramientos está en la documentación de migración.
Verificación: ¿Las firmas de los métodos están actualizadas? Varios métodos de uso común cambiaron sus firmas o fueron renombrados:
move_and_slide()ya no recibe argumentos. Lee la propiedadvelocityintegrada del nodo. (Documentación de CharacterBody2D)instance()→instantiate()set_shader_param()→set_shader_parameter()map_to_world()→map_to_local()(GridMap y TileMap)change_scene()→change_scene_to_file()Thread.start(self, "__method", args)→Thread.start(__method.bind(args))Thread.is_active()→Thread.is_alive()
Verificación: ¿Las conexiones de señales usan la sintaxis callable?
El antiguo patrón connect("signal_name", target, "method_name") está obsoleto. Godot 4 usa conexiones basadas en callables:
# Antiguo (Godot 3)
button.connect("pressed", self, "_on_button_pressed")
# Actual (Godot 4)
button.pressed.connect(_on_button_pressed)La forma callable da validación en tiempo de compilación. Las conexiones basadas en strings se rompen silenciosamente en tiempo de ejecución si renombras el método. (Documentación de Signal)
Verificación: ¿Las constantes y los nombres de señales están actualizados?
Las constantes de color cambiaron de formato (por ejemplo, Color.palegreen → Color.PALE_GREEN). Algunos nombres de señales fueron renombrados (por ejemplo, CanvasItem.hide → hidden). Revisa las tablas de renombramientos en la documentación de migración.
2. Callbacks del ciclo de vida
¿El código se ejecuta en el callback correcto?
Esta es la categoría más peligrosa porque el código en el callback equivocado compila, se ejecuta y parece funcionar. Falla en condiciones reales: diferentes tasas de fotogramas, casos límite de física o variación de hardware. La documentación de notificaciones de Godot es explícita sobre qué callback sirve a qué propósito.
Verificación: ¿El movimiento de física está en _physics_process()?
_process() se ejecuta en cada fotograma renderizado y depende de la tasa de fotogramas. _physics_process() se ejecuta a una tasa fija (60 veces por segundo por defecto). Cualquier código que llame a move_and_slide(), move_and_collide(), o manipule directamente la velocidad de un cuerpo físico pertenece a _physics_process(). (Introducción a la física)
Verificación: ¿La entrada se maneja en el lugar correcto?
Para eventos discretos (pulsación de tecla, clic de botón), prefiere _input() o _unhandled_input(). Para estado continuo (si la tecla está presionada), _process() o _physics_process() con Input.is_action_pressed() es apropiado. Consultar la entrada en cada fotograma dentro de _process() cuando solo se necesita para movimiento de física es un patrón común generado por IA.
Verificación: ¿_ready() hace configuración, no trabajo continuo?
_ready() se ejecuta una vez cuando el nodo entra al árbol. Los hijos ejecutan _ready() antes que los padres. Si la inicialización depende de que un nodo hermano o padre esté listo, considera usar await owner.ready o diferir la llamada de configuración.
3. Higiene de señales
¿Las señales mantienen el código desacoplado?
El sistema de señales de Godot permite que los objetos reaccionen a eventos sin referenciarse directamente entre sí. La regla práctica es “llamar hacia abajo, señalar hacia arriba”: los nodos padre pueden llamar métodos en los hijos directamente, pero los hijos deben comunicarse hacia arriba a través de señales. El código generado por IA frecuentemente viola esto haciendo que los hijos accedan a padres o hermanos.
Verificación: ¿Se usan señales en lugar de referencias directas al padre?
Si un nodo hijo necesita notificar a su padre que algo sucedió, debe emitir una señal. El padre se conecta a esa señal. El hijo no debe llamar a get_parent().some_method().
Verificación: ¿Las conexiones de señales están en el lugar correcto?
El nodo que le importa el evento debe ser dueño de la conexión. Típicamente, los nodos padre se conectan a las señales de sus hijos en _ready(). Evita conectar señales en partes profundamente anidadas o distantes del árbol.
Verificación: ¿Las señales se desconectan cuando es necesario?
Si los nodos se agregan y eliminan dinámicamente, las conexiones de señales persistentes pueden causar errores o comportamiento inesperado. Verifica si se necesita limpieza con disconnect() o queue_free().
4. Arquitectura del árbol de escena
¿El código asume una estructura de árbol fija?
Godot está construido alrededor de escenas componibles que se pueden instanciar en cualquier lugar. Las rutas y referencias de padre codificadas rompen esta componibilidad. La documentación de organización de escenas dice que las subescenas reutilizables deberían funcionar sin requerir detalles sobre su entorno.
Verificación: ¿El script navega hacia arriba con ..?
get_node(".."), get_parent(), y rutas como ../../Player son frágiles. Se rompen si la escena se reparenta, se reutiliza en otro contexto, o se reestructura. La documentación de nodos e instancias de escena dice que evitar .. es la mejor práctica.
Verificación: ¿Debería ser una referencia @export en lugar de una ruta codificada?
@export var target: Node te permite conectar referencias en el editor. Es más robusto que get_node("../Player") porque sobrevive a la reestructuración del árbol y hace explícitas las dependencias.
Verificación: ¿Debería usar grupos en lugar de referencias directas?
Los grupos te permiten etiquetar nodos y acceder a ellos sin conocer su ruta. get_tree().get_nodes_in_group("enemies") es más resiliente que iterar sobre los hijos por nombre.
Verificación: ¿Las relaciones padre-hijo son significativas? La documentación dice que las relaciones padre-hijo deberían representar contención real: si eliminar al padre no debería eliminar al hijo, el hijo puede pertenecer a otro lugar del árbol. La IA a menudo anida nodos por conveniencia en lugar de por corrección semántica.
5. Seguridad de tipos y advertencias
¿El proyecto usa las herramientas de seguridad integradas de Godot?
GDScript admite tipado estático y tiene un sistema de advertencias integrado. Ambos son opcionales pero reducen significativamente las sorpresas en tiempo de ejecución. La documentación dice que los tipos estáticos ayudan a detectar errores sin ejecutar el código y mejoran el autocompletado del editor.
Verificación: ¿Los parámetros de función y los tipos de retorno están anotados?
# Sin tipar (funciona pero es riesgoso)
func take_damage(amount):
health -= amount
# Tipado (detecta errores en tiempo de análisis)
func take_damage(amount: int) -> void:
health -= amountLa mejor práctica es todo o nada. La documentación advierte que mezclar código tipado y sin tipar en el mismo proyecto crea confusión.
Verificación: ¿Las advertencias se toman en serio? El sistema de advertencias de Godot detecta variables no usadas, código inalcanzable y patrones que pueden llevar a errores en tiempo de ejecución. Las advertencias pueden escalarse a errores en la configuración del proyecto. Si tu proyecto ignora todas las advertencias, los bugs se esconden.
Verificación: ¿Las anotaciones @warning_ignore están justificadas?
Godot admite @warning_ignore("unused_variable") y anotaciones similares. Cada una debería ser intencional, no una forma de silenciar ruido. Durante la revisión, pregunta: ¿este ignore está ocultando un problema real, o es una excepción deliberada?
6. Gestión de recursos
¿El código carga, crea y libera cosas de forma segura?
El sistema de recursos de Godot es poderoso pero tiene patrones que la IA frecuentemente hace mal, especialmente en torno a la carga, instanciación y limpieza.
Verificación: ¿load() frente a preload() es intencional?
preload() carga en tiempo de compilación y requiere una ruta de string constante. load() se ejecuta en la línea donde se llama. Usa preload() para recursos que siempre necesitas. Usa load() para recursos cargados condicionalmente o dinámicamente. La IA tiende a usar load() en todas partes porque es más flexible, pero esto crea carga innecesaria en tiempo de ejecución.
Verificación: ¿Las escenas empaquetadas se instancian correctamente?
En Godot 4, las escenas guardadas son recursos PackedScene. Llamas a instantiate() (no instance(), que es el nombre de Godot 3) para crear el árbol de nodos. Verifica que las escenas instanciadas se agreguen al árbol con add_child().
Verificación: ¿Los nodos se liberan de forma segura?
Usa queue_free() a menos que tengas una razón específica para no hacerlo. free() destruye el nodo inmediatamente, y cualquier referencia a él se vuelve nula al instante. queue_free() espera hasta el final del fotograma actual, lo cual es más seguro. La documentación recomienda queue_free() como opción por defecto.
Verificación: ¿Los autoloads se usan con moderación?
Los autoloads son accesibles globalmente, pero siguen siendo nodos en el árbol de escena. Nunca deben eliminarse con free() o queue_free() en tiempo de ejecución o el motor se bloqueará. El código generado por IA a veces trata los autoloads como administradores desechables. Evalúa si el estado global realmente necesita ser global o podría ser un recurso o un grupo en su lugar.
Lo que este checklist no cubre
Este checklist cubre revisión de código: corrección, arquitectura y patrones. No reemplaza:
- Linters y formateadores. Herramientas como
gdscript-toolkity las advertencias integradas de Godot detectan sintaxis, formato, variables no usadas y algunos problemas de tipos. Úsalas. Son complementarias. - Playtesting. La revisión de código detecta problemas estructurales. No detecta “esto no se siente bien” o “el salto es demasiado flotante”. Eso es testing.
- Diseño de arquitectura. Este checklist pregunta “¿la arquitectura es sólida?”. No te dice qué arquitectura usar. Para eso, lee la sección de mejores prácticas de Godot.
Automatizar el checklist
Puedes recorrer esta lista manualmente en cada PR. O puedes automatizarla.
Surmado Code Review para Godot revisa cada push a un pull request de GitHub contra la documentación oficial de Godot 4.6, el contexto de tu repo y tu STANDARDS.MD. Detecta errores de versión, mal uso del ciclo de vida, patrones obsoletos, rutas frágiles del árbol de escena y cualquier regla personalizada que definas.
Gratis para 10 PR al mes. $15/mes para 100. Sin precios por asiento.
El checklist es qué revisar. Surmado Code Review es cómo revisarlo en cada PR sin tener que mirar fijamente los diffs.
Instala Surmado Code Review para Godot (Gratis) →
¿No estás seguro sobre una API o patrón específico de Godot? Pregúntale a GDScout contra la documentación oficial de 4.6. Gratis, con citas.
Preguntas y respuestas
¿Existe un checklist de revisión de código para GDScript? Sí. El checklist de revisión de código en GDScript cubre seis categorías: corrección de versión (patrones de Godot 3 frente a 4), callbacks del ciclo de vida (_process frente a _physics_process), higiene de señales, arquitectura del árbol de escena, seguridad de tipos y advertencias, y gestión de recursos. Cada verificación está basada en la documentación oficial de Godot 4.6.
¿Qué debería revisar en una revisión de código de Godot? Una revisión de código de Godot debería verificar la corrección de versión (sin patrones de Godot 3 en un proyecto de Godot 4), el uso correcto de los callbacks del ciclo de vida, conexiones de señales basadas en callables, una arquitectura de árbol de escena componible sin rutas de padre frágiles, cumplimiento de tipado estático y advertencias, y carga segura de recursos y limpieza de nodos. El checklist de revisión de código en GDScript ofrece verificaciones específicas para cada categoría con enlaces a la documentación oficial.
¿Tiene Godot una herramienta de revisión de código? Las herramientas integradas de Godot incluyen un sistema de advertencias de GDScript y soporte de tipado estático, que detectan errores de sintaxis y de tipos. Para revisión de código a nivel de PR, Surmado Code Review para Godot revisa los pull requests de GitHub contra la documentación oficial de Godot 4.6 y el STANDARDS.MD de un equipo. Detecta errores de versión, mal uso del ciclo de vida, patrones obsoletos y problemas de arquitectura que los linters no cubren. Gratis para 10 PR por mes.
¿Cuáles son los errores más comunes en el código de Godot generado por IA? Los errores más comunes son usar tipos de nodos y firmas de métodos renombrados de Godot 3, colocar el movimiento de física en _process() en lugar de _physics_process(), usar conexiones de señales basadas en strings obsoletas, codificar rutas frágiles de nodos padre y hermanos, y usar load() en lugar de preload() para recursos en tiempo de compilación. Estos patrones pasan el linting y compilan sin errores pero causan fallos en tiempo de ejecución o comportamiento inconsistente.
¿En qué se diferencia un checklist de revisión de código de un linter de GDScript? Un linter de GDScript detecta errores de sintaxis, problemas de formato, variables no usadas y algunos problemas de tipos. Un checklist de revisión de código evalúa preocupaciones de más alto nivel: si esta es la API correcta para la versión del motor, si el código de movimiento está en el callback correcto, si las conexiones de señales son modernas, si la arquitectura del árbol de escena es componible, y si el código sigue los estándares específicos del proyecto. Los linters y la revisión de código son complementarios.
¿Qué es STANDARDS.MD? STANDARDS.MD es un documento Markdown que define los estándares de codificación que un equipo aplica durante la revisión de código. En Surmado Code Review, STANDARDS.MD se crea a través de una conversación con Scout, el agente de IA de Surmado, en lugar de editando un archivo de configuración. El documento puede incluir reglas específicas de Godot como “siempre usar _physics_process para movimiento de CharacterBody” o “sin navegación de rutas de padre con get_node(‘..’)”.