Consejos de nomenclatura y estilo de código para scripting en C# en Unity

Un identificador es cualquier nombre que asignes a un tipo (clase, interfaz, estructura, delegado o enumeración), miembro, variable o espacio de nombres.

Evita caracteres especiales (barra invertida, símbolos, caracteres Unicode) en tus identificadores, aunque C# los permite. Estos pueden interferir con ciertas herramientas de línea de comandos de Unity. Evita caracteres inusuales para asegurar la compatibilidad con la mayoría de las plataformas.

No puedes definir variables con espacios en el nombre porque C# utiliza el carácter de espacio para separar identificadores. Los esquemas de mayúsculas pueden aliviar el problema de tener que usar nombres compuestos o frases en el código fuente.

A continuación se enumeran varias convenciones de nomenclatura y mayúsculas bien conocidas:

Camel case (camelCase)

También conocido como camel caps, camel case es la práctica de escribir frases sin espacios ni puntuación, separando las palabras con una sola letra mayúscula. La primera letra es minúscula. Las variables locales y los parámetros de método son camel case. Por ejemplo:

examplePlayerController

puntosDeSaludMax

endOfFile

Pascal case (PascalCase)

El case Pascal es una variación del case de camello, donde la letra inicial está en mayúscula. Usa esto para nombres de clases, campos públicos y métodos en el desarrollo de Unity. Por ejemplo:

ControladorDeJugadorEjemplo

PuntosDeSaludMax

EndOfFile

Snake case (snake_case)

En este caso, los espacios entre palabras se reemplazan con un carácter de guion bajo. Por ejemplo:

example_player_controller

max_health_points

end_of_file

Kebab case (kebab-case)

Aquí, los espacios entre palabras se reemplazan con guiones. Las palabras aparecen en un "escarbadiente" de caracteres de guion. Por ejemplo:

example-player-controller

Max-health-points

end-of-file

metodología-de-convenciones-de-nomenclatura

El Kebab-case se utiliza ampliamente en tecnologías web y, en particular, para CSS. También lo recomendamos para su uso con UI Toolkit USS.

Hungarian notation

El nombre de la variable o función a menudo indica su intención o tipo. Por ejemplo:

int iCounter

string strPlayerName

La notación húngara es una convención más antigua y no es común en el desarrollo de Unity.

Considera estas reglas para tus variables y campos:

• Usa sustantivos para los nombres de las variables: Los nombres de las variables deben ser descriptivos, claros y sin ambigüedades porque representan una cosa o estado. Así que usa un sustantivo al nombrarlas, excepto cuando la variable sea del tipo bool (ver más abajo).
• Prefija los Booleans con un verbo: Estas variables indican un valor verdadero o falso. A menudo son la respuesta a una pregunta, como – ¿está corriendo el jugador? ¿Está el juego terminado? Prefíjalos con un verbo para hacer su significado más evidente. A menudo esto se empareja con una descripción o condición, por ejemplo, isDead, isWalking, hasDamageMultiplier, etc.
• Usa nombres significativos. No los abrevies (a menos que sea matemáticas): Los nombres de tus variables deben revelar su intención. Elige nombres que sean fáciles de pronunciar y buscar, no solo para tus colegas, sino también para proporcionar contexto adicional al código al usar herramientas de IA, ya que esto puede contribuir a una generación de código y sugerencias más precisas. Elige nombres de identificadores que sean fácilmente legibles. Por ejemplo, una propiedad llamada HorizontalAlignment es más legible que AlignmentHorizontal. Las variables de una sola letra son adecuadas para bucles y expresiones matemáticas, pero de lo contrario, no las abrevies. La claridad es más importante que cualquier tiempo ahorrado al omitir algunas vocales. Podrías sentirte tentado a usar nombres cortos "basura" al prototipar, pero esto no te ahorrará tiempo si necesitas refactorizar el código más adelante. Elige nombres significativos desde el principio.
• Usa notación Pascal (MyPropertyName) para campos públicos. Usa notación camel (myPrivateVariable) para variables privadas: Para una alternativa a los campos públicos, utiliza propiedades con un getter público (ver Formateo arriba y abajo).
• Considera usar prefijos o codificación especial: Algunas guías sugieren agregar un prefijo a las variables miembro privadas con un guion bajo (_) para diferenciarlas de las variables locales. En nuestras guías de estilo usamos prefijos para variables miembro privadas (m_), constantes (k_) o variables estáticas (s_), para que el nombre pueda revelar más sobre la variable de un vistazo. Por ejemplo, movementSpeed se convierte en m_movementSpeed. Mezclar PascalCase con el prefijo como m_MovementSpeed también es una opción, pero generalmente se usa menos en C# moderno. Alternativamente, usa la palabra clave this para distinguir entre variables de miembro y locales en contexto y omitir el prefijo. Los campos y propiedades públicos generalmente no tienen prefijos. Las variables locales y los parámetros utilizan camel case sin prefijo. Muchos desarrolladores evitan esto y confían en el editor en su lugar. Sin embargo, no todos los IDEs soportan resaltado y codificación de colores, y algunas herramientas no pueden mostrar contexto enriquecido en absoluto.
• Los campos se inicializan automáticamente a sus valores predeterminados: El valor predeterminado es típicamente 0 para tipos numéricos como int, mientras que los campos de tipo referencia (por ejemplo, objetos) se inicializan en null por defecto, y los campos bool se inicializan en false por defecto. Dado esto, establecer explícitamente un campo en su valor predeterminado generalmente es innecesario.
• Nombra las variables constantes con k_ como prefijo y en PascalCase: Esto ayuda a distinguir las constantes de las variables o propiedades regulares, y hace que el código sea más fácil de leer y mantener.
• Especifica (o omite) modificadores de nivel de acceso de manera consistente: Si omites el modificador de acceso, el compilador asumirá que el nivel de acceso es privado. Esto funciona bien, pero sé consistente en cómo omites el modificador de acceso por defecto. Las pautas de MSFT recomiendan especificar explícitamente privado para dejar claro el nivel de acceso y evitar cualquier ambigüedad. Otras guías argumentan que deberías eliminar los especificadores de acceso redundantes (omitir 'privado' en el ámbito de tipo) y, de manera similar, eliminar inicializadores redundantes (es decir, no '= 0' en los ints, '= null' en tipos de referencia, etc.). Recuerda que necesitarás usar protected si quieres esto en una subclase más tarde. Sin embargo, generalmente se considera una buena práctica especificar los modificadores de nivel de acceso.
• Prioriza la legibilidad sobre la brevedad: Como este ejemplo de la documentación de MSFT muestra, el nombre de la propiedad CanScrollHorizontally es mejor que ScrollableX (una referencia oscura al eje X).
• Usa una declaración de variable por línea: Es menos compacto, pero mejora la legibilidad.
• Evita nombres redundantes: Si tu clase se llama Player, no necesitas crear variables miembro llamadas PlayerScore o PlayerTarget. Redúcelas a Score o Target.
• Elimina inicializadores redundantes (es decir, no '= 0' en los enteros, '= null' en tipos de referencia, etc.).
• Evita chistes o juegos de palabras: Aunque pueden provocar una risa ahora, las variables infiniteMonkeys o dudeWheresMyChar no resistirán después de unas pocas lecturas, y lo más importante, violan nuestro objetivo previamente declarado de nombrar revelando contexto.
• Limita el uso de la var palabra clave solo a variables locales de tipo implícito si ayuda a la legibilidad y el tipo es obvio: Especifica cuándo usar var en tu guía de estilo. Por ejemplo, muchos desarrolladores evitan var cuando oscurece el tipo de la variable o con tipos primitivos fuera de un bucle.

Los enums son tipos de valor especiales definidos por un conjunto de constantes nombradas. Por defecto, las constantes son enteros, contando desde cero.

Usa la notación Pascal para nombres y valores de enum. Puedes colocar enums públicos fuera de una clase para hacerlos globales. Usa un sustantivo singular para el nombre del enum ya que representa un solo valor de un conjunto de valores posibles. No deben tener prefijo ni sufijo.

Nota: Los enums de bits marcados con el System.FlagsAttribute atributo son la excepción a esta regla. Normalmente los pluralizas ya que representan más de un tipo.

Sigue estas reglas estándar al nombrar tus clases e interfaces:

• Usa sustantivos o frases nominales en notación Pascal para nombres de clases: Esto distingue los nombres de tipo de los métodos, que se nombran con frases verbales.
• Si tienes un Monobehaviour en un archivo, el nombre del archivo fuente debe coincidir: Puedes tener otras clases internas en el archivo, pero solo debe existir un Monobehaviour por archivo.
• Prefija los nombres de las interfaces con una I mayúscula: Sigue esto con un adjetivo que describa la funcionalidad.

En C#, cada instrucción ejecutada se realiza en el contexto de un método.

Nota: "función" y "método" a menudo se utilizan indistintamente en el desarrollo de Unity. Sin embargo, dado que no puedes escribir una función sin incorporarla en una clase en C#, "método" es el término aceptado.

Los métodos realizan acciones, así que aplica estas reglas para nombrarlos adecuadamente:

• Comienza el nombre con un verbo o frases verbales: Agrega contexto si es necesario. p.ej. ObtenerDirección, EncontrarObjetivo, etc.
• Usa camel case para los parámetros: Formatea los parámetros pasados al método como variables locales.
• Los métodos que devuelven bool deben hacer preguntas: Al igual que las variables booleanas, prefija los métodos con un verbo si devuelven una condición de verdadero-falso. Esto los formula en forma de pregunta, p.ej. ¿EstáJuegoTerminado?, ¿HaComenzadoTurno?.

Los eventos en C# implementan el patrón observador. Este patrón de diseño de software define una relación en la que un objeto, el sujeto (o publicador), puede notificar a una lista de objetos dependientes llamados observadores(o suscriptores). Así, el sujeto puede transmitir cambios de estado a sus observadores sin acoplar fuertemente los objetos involucrados. Puedes aprender más sobre el uso del observador y otros patrones de diseño en tus proyectos de Unity en el libro electrónico Mejora tu código con patrones de diseño y SOLID.

Nombra el evento con una frase verbal. Elige un nombre que comunique el cambio de estado con precisión. Usa el presente o el participio pasado para indicar eventos "antes" o "después". Por ejemplo, especifica "AbrirPuerta" para un evento antes de abrir una puerta o "PuertaAbierta" para un evento después.

En la mayoría de los casos, el Action delegado puede manejar los eventos necesarios para el juego. Puedes pasar de 0 a 16 parámetros de entrada de diferentes tipos con un tipo de retorno void. Usar el delegado predefinido ahorra código.

Nota: También puedes usar los delegados EventHandler o EventHandler. Acuerda como equipo cómo todos implementarán los eventos.

El sujeto que invoca el evento típicamente lo hace desde un método prefijado con "On", p.ej. "OnAbrirPuerta" o "OnPuertaAbierta."

Si el sujeto se llama “EventosJuego,” tus observadores pueden tener un método llamado “EventosJuego_AperturaPuerta” o “EventosJuego_PuertaAbierta.” Tenga en cuenta que esto se llama el "método de manejo de eventos", no debe confundirse con el delegado EventHandler.

Cree EventArgs personalizados solo cuando sea necesario. Si necesita pasar datos personalizados a su Evento, cree un nuevo tipo de EventArgs, ya sea heredado de System.EventArgso de una estructura personalizada.

Utilice namespaces para asegurarse de que sus clases, interfaces, enumeraciones, etc. no entren en conflicto con las existentes de otros espacios de nombres o el espacio de nombres global. Los espacios de nombres también pueden prevenir conflictos con activos de terceros de la Asset Store.

Al aplicar namespaces:

• Utilice PascalCase sin símbolos especiales ni guiones bajos.
• Agregue una directiva using en la parte superior del archivo para evitar escribir repetidamente el prefijo del espacio de nombres.
• Crea sub-namespaces también. Utiliza el operador punto (.) para delimitar los niveles de nombre, permitiéndote organizar tus scripts en categorías jerárquicas. Por ejemplo, puede crear MyApplication.GameFlow, MyApplication.AI, MyApplication.UI, y así sucesivamente para contener diferentes componentes lógicos de su juego.
• En general, se considera una buena práctica tener espacios de nombres que reflejen la estructura de carpetas del proyecto, ya que agrupar lógicamente clases y componentes relacionados facilita encontrar y entender la estructura de la base de código.

En el código, estas clases se refieren como Enemy.Controller1 y Enemy.Controller2, respectivamente. Agregue una línea using para ahorrar escribir el prefijo:

using Enemy;

Cuando el compilador encuentra los nombres de clase Controller1 y Controller2, entiende que te refieres a Enemy.Controller1 y Enemy.Controller2.

Si el script necesita referirse a clases con el mismo nombre de diferentes namespaces, utiliza el prefijo para diferenciarlas. Por ejemplo, si tiene una clase Controller1 y Controller2 en el espacio de nombres Player, puede escribir Player.Controller1 y Player.Controller2 para evitar conflictos. De lo contrario, el compilador informará un error.

using Enemy;