Usar comentarios en nuestro código GML

Cuando estamos programando, suele ser útil añadir comentarios a nuestro código, ya que nos facilita mucho la tarea de comprender que estamos codificando y detectar posibles errores. Esto cobra más importancia cuando estamos revisando el código que escribimos hace tiempo o trabajamos con un equipo de personas, dónde otro puede ver el código GML. Veamos cuándo utilizarlos y cómo se hace.

¿Como se añaden comentarios a nuestro código?

Ya dijimos en las acciones que podemos añadir a un evento que tenemos una acción de comentario, con el símbolo . Cuando escribimos código GML, se puede añadir un comentario corto si usamos // al principio del mismo. Por ejemplo:

// Esto es un comentario

Los comentarios cortos los podemos usar en cualquier lugar de nuestro código, incluso después de una sentencia

a = b + 1; //Aquí estamos sumando
if (a < 10) { //Comprobación de a
    b++;
}

Si queremos usar varias líneas de comentario, tenemos una opción más cómoda que añadir // en cada línea. Podemos usar /* */, dónde /* sería el inicio del comentario y */ sería el final. Un ejemplo:

/* Esto es un comentario
con varias líneas
de uso.
*/

No se pueden anidar comentarios. Esto daría error

/*
Prueba comentario
/*Otro comentario */
*/

Ya que el último cierre no lo detecta. Sí que podríamos usar el símbolo //

/* Esto no da error
Prueba comentario
//Otro comentario 
*/

Otro uso muy interesante de los comentarios es una utilidad exclusiva del funcionamiento de Game Maker Studio. Cuando añadimos uno o varios Execute Code, nos hemos fijado que siempre aparece el texto Execute a piece of code.

Podemos cambiar este texto por el que queramos, si al inicio del código GML añadimos el símbolo ///. Si, con 3 barras. Lo útil sería añadir una pequeña descripción de lo que hace el código y así desde el editor de objetos es más fácil saber dónde entrar.

///Comprobar posición 

Esto funciona también para scripts, ya que nos ayuda saber cómo usamos los argumentos. Por ejemplo, si tenemos esto en un script

Aparte de saber en el script que el argument0 nos referimos a num achievement, cuando llamamos desde un evento a nuestro script, lo veremos en la barra inferior del editor de GML, igual que si fuese una función de sistema

¿Cuando se añaden comentarios?

Aquí ya viene el hábito de cada uno a la hora de programar. Para empezar, destacar que no añadir ningún comentario o añadir muchísimos de ellos no implica nada en el rendimiento del código, simplemente cuando se compila esas líneas son ignoradas.
Los comentarios se crean para hacer el código más entendible, así que hay que decir que hace el código, no como lo hace. Por ejemplo, si al inicio del código vemos esto

//inicializar variables
sr = 10;
hp = 100;

¿Es necesario ese comentario? No se entiende que esas variables sirven para inicializar? Aquí ya lo decide cada uno. Pero si que debemos evitar cosas absurdas:

if (b == 3)     // Si b vale 3, ...
     a++; // ... incrementamos a
  ...

Si el código es lo suficientemente claro,
También he visto en muchos scripts una explicación breve de lo que hace, explicando los argumentos de entrada y el posible resultado de salida. Ejemplo:

/*
usage:
diff = angle_difference(angle1,angle2);

angle1 first direction in degrees, real
angle2 second direction in degrees, real

returns: difference of the given angles in degrees, -180 to 180

GMLscripts.com
*/

También existe una parte práctica el uso de comentarios en GML. Si queremos deshabilitar parte del código, ya sea porque es obsoleto o estamos comprobando errores, y no queremos borrarlo, podemos usar los comentarios para que no se use. Existen otros lenguajes de programación, como Java, que utilizan los comentarios para generar documentación o para el control de versiones, lo comento porque el uso de SVN en Game Maker para el control de versiones lo desconozco, y no se si se utilizan los comentarios para su uso.
Para finalizar, os paso un enlace sobre consejos a la hora de comentar el código, de variablenotfound.
Aprovechando que hablamos de comentarios, deja los tuyos más abajo ^_^.