Power Apps Standards – Comentar Código
¿Para Qué Escribir Comentarios en el Código? Las «Notas al Margen» para tu Yo del Futuro
Imagina que escribes una fórmula súper ingeniosa en tu Power App. En ese momento, te parece la cosa más lógica del mundo. Pero vuelves a verla dentro de seis meses… y no tienes ni la más remota idea de qué hace o, más importante, por qué lo hiciste así.
Los comentarios son precisamente eso: notas al margen que te dejas a ti mismo y a otros desarrolladores para explicar la intención de tu código. Son para los humanos, no para el ordenador.
Saber lo que querías que hiciera el código es súper útil, sobre todo cuando algo falla. Si tu comentario dice «aquí calculo el descuento del 15%» y el resultado que ves es un 20%, ¡bingo!, ya sabes dónde está el error.
El Debate de los Informáticos: ¿Comentarios Sí o No?
Entre los programadores hay un eterno debate sobre si se debe comentar el código o no. Algunos dicen que un buen código se explica por sí mismo.
La respuesta corta para nosotros es: en Power Apps, sí, úsalos. Ahorran muchísimo tiempo.
¡Ojo! Esto no es una excusa para escribir código enrevesado. Un comentario no arregla un código que no hay por dónde cogerlo. Sería como cocinar un plato horrible y ponerle un cartelito que diga «Sabe bien». ¡Mejor cocina bien desde el principio!
El Estilo: Cómo Dejar Comentarios «Elegantes»
Para que todo quede limpio y ordenado, sigue estas simples reglas de estilo:
- Pon el comentario en su propia línea, justo encima del código que quieres explicar.
- Nunca pongas un comentario al lado de una línea de código. Queda desordenado.
- Empieza el comentario con mayúscula.
- Termina la frase con un punto.
Los Dos Tipos de «Post-it» que Puedes Usar
En Power Apps tienes dos maneras de dejar notas:
La Nota Rápida (Comentario de Línea)
Se usa para una sola frase. Simplemente pones dos barras // al principio.
Sintaxis: // [Aquí va tu comentario]
Ejemplo:
Fragmento de código
// Validar la orden de trabajo para asegurar que no será rechazada al enviarla.
If(IsBlank(txt_FirmaCliente.Text), DisplayMode.Disabled, DisplayMode.Edit)
El Parrafito Explicativo (Comentario de Bloque)
Perfecto para cuando necesitas explicar algo con más detalle. Empieza con /* y termina con */.
Sintaxis: /* [Aquí va tu súper comentario de varias líneas] */
Ejemplo:
Fragmento de código
/*
Pantalla de Detalles de la Orden:
– Se usa un único formulario para crear, editar y ver un registro.
Así minimizamos el número de controles en la app.
– Envía un PDF firmado por email al jefe del empleado
después de enviar el formulario para guardarlo como copia.
*/
Visible = locModoFormulario = "Editar"
Consejos de Oro para Escribir Buenos Comentarios
Aquí viene lo más importante. No se trata de escribir por escribir.
👍 HAZ ESTO: Explica el «PORQUÉ» (la intención). Un buen comentario es como el «cómo se hizo» de una película. No describe lo que ves en pantalla, sino por qué el director tomó esa decisión.
- Ejemplo:
// Calcular el total final incluyendo el impuesto de tarifa especial para Canarias.
👎 NO HAGAS ESTO: No expliques el «QUÉ» (lo que es obvio). El código ya dice lo que hace. No hace falta que lo traduzcas. Eso es ruido.
- Mal ejemplo:
// Poner el valor de la variable 'NombreUsuario' a "Juan"Set(gblNombreUsuario, "Juan")(¡Ya se ve que hace eso!)
👍 HAZ ESTO: Si cambias el código, ¡actualiza el comentario! Un comentario anticuado es peor que no tener ningún comentario, porque miente y confunde. Si cambias la receta, ¡tacha la nota antigua!
👎 NO HAGAS ESTO: No te pases comentando cada línea. Comentar en exceso es contraproducente. Cada comentario es algo más que tienes que mantener, y si hay demasiados, la gente dejará de leerlos. Es como acumular «deuda»: al final te da más trabajo del que te ahorra.
👍 HAZ ESTO: Escribe frases completas y con un lenguaje normal. Escribe como si se lo estuvieras explicando a un compañero de trabajo.
👎 NO HAGAS ESTO: Evita abreviaturas, siglas raras o jerga. No escribas «Calc. imp xq el usr es de Fuerteven.». Escribe la frase completa para que cualquiera, incluso alguien nuevo en el proyecto, lo pueda entender.