Limpia tu código: Cómo crear su propio estilo de código C#

Aunque hay más de una forma de dar formato al código Unity C#, acordar un estilo de código coherente para su proyecto permite a su equipo desarrollar una base de código limpia, legible y escalable. En este blog, ofrecemos algunas directrices y ejemplos que puede utilizar para desarrollar y mantener su propia guía de estilo de código.

Tenga en cuenta que sólo se trata de recomendaciones basadas en las proporcionadas por Microsoft. Esta es su oportunidad de inspirarse y decidir qué es lo mejor para su equipo.

Idealmente, un proyecto Unity debería dar la sensación de haber sido desarrollado por un único autor, sin importar cuántos desarrolladores trabajen realmente en él. Una guía de estilo puede ayudar a unificar su enfoque para crear una base de código más cohesionada.

Es una buena idea seguir las normas del sector siempre que sea posible y consultar las guías de estilo existentes como punto de partida para crear la suya propia. En colaboración con expertos internos y externos de Unity, hemos publicado un nuevo libro electrónico, Create a C# style guide: Escriba código más limpio que escale para inspirarse, basándose en el estilo C# integral de Microsoft.

La guía de estilo de C# de Google es otro gran recurso para definir directrices sobre convenciones de nomenclatura, formato y comentarios. Una vez más, no hay un método correcto o incorrecto, pero hemos optado por seguir las normas de Microsoft para nuestra propia guía.

Nuestro libro electrónico, junto con un archivo C# de ejemplo, están disponibles gratuitamente. Ambos recursos se centran en las convenciones de codificación más comunes que encontrarás al desarrollar en Unity. Todos estos son, esencialmente, un subconjunto de las directrices de diseño de Microsoft Framework, que incluyen un amplio número de mejores prácticas más allá de lo que cubrimos en este post.

Le recomendamos que adapte las directrices de nuestra guía de estilo a las preferencias de su equipo. Estas preferencias deben tener prioridad sobre nuestras sugerencias y las directrices de diseño de Microsoft Framework si entran en conflicto.

La elaboración de una guía de estilo requiere una inversión inicial, pero dará sus frutos más adelante. Por ejemplo, gestionar un único conjunto de normas puede reducir el tiempo que los desarrolladores dedican a ponerse al día si pasan a otro proyecto.

Por supuesto, la coherencia es la clave. Si sigue estas sugerencias y necesita modificar su guía de estilo en el futuro, unas pocas operaciones de búsqueda y sustitución pueden migrar rápidamente su código base.

Concéntrese en crear una guía de estilo pragmática que se adapte a sus necesidades cubriendo la mayoría de los casos de uso cotidiano. No te compliques la vida intentando tener en cuenta todos los casos extremos desde el principio. La guía evolucionará orgánicamente con el tiempo, a medida que su equipo la vaya utilizando de proyecto en proyecto.

La mayoría de las guías de estilo incluyen normas básicas de formato. Mientras tanto, las convenciones específicas de nomenclatura, la política de uso de espacios de nombres y las estrategias para las clases son áreas algo abstractas que pueden perfeccionarse con el tiempo.

Veamos algunas convenciones comunes de formato y nomenclatura que puede tener en cuenta para su guía de estilo.

Los dos estilos de indentación comunes en C# son el estilo Allman, que coloca las llaves de apertura en una nueva línea (también conocido como el estilo BSD de BSD Unix), y el estilo K&R, o "estilo de una llave verdadera", que mantiene la llave de apertura en la misma línea que la cabecera anterior.

En un esfuerzo por mejorar la legibilidad, hemos elegido el estilo Allman para nuestra guía, basado en las directrices de diseño de Microsoft Framework:

Tipo de bloque desconocido "codeBlock", especifique un serializador para él en la propiedad `serializers.types`.

Sea cual sea el estilo que elija, asegúrese de que todos los programadores de su equipo lo siguen.

La guía también debe indicar si deben incluirse los corchetes de las sentencias multilínea anidadas. Si bien la eliminación de las llaves en el siguiente ejemplo no arrojará un error, puede ser confuso de leer. Por eso nuestra guía recomienda aplicar refuerzos para mayor claridad, aunque sean opcionales.

Tipo de bloque desconocido "codeBlock", especifique un serializador para él en la propiedad `serializers.types`.

Algo tan sencillo como el espaciado horizontal puede mejorar el aspecto de su código en pantalla. Aunque sus preferencias personales de formato pueden variar, he aquí algunas recomendaciones de nuestra guía de estilo para mejorar la legibilidad general:

• Añada espacios para reducir la densidad del código: los espacios en blanco adicionales pueden dar una sensación de separación visual entre las partes de una línea.

Tipo de bloque desconocido "codeBlock", especifique un serializador para él en la propiedad `serializers.types`.

• Utilice un solo espacio después de la coma, entre los argumentos de las funciones.

Tipo de bloque desconocido "codeBlock", especifique un serializador para él en la propiedad `serializers.types`.

• No añadas un espacio después del paréntesis y los argumentos de la función.

Tipo de bloque desconocido "codeBlock", especifique un serializador para él en la propiedad `serializers.types`.

• No utilice espacios entre el nombre de una función y los paréntesis.

Tipo de bloque desconocido "codeBlock", especifique un serializador para él en la propiedad `serializers.types`.

• Evite los espacios entre paréntesis.

Tipo de bloque desconocido "codeBlock", especifique un serializador para él en la propiedad `serializers.types`.

• Utilice un solo espacio antes de las condiciones de control de flujo: Añada un espacio entre el operador de comparación de flujo y los paréntesis.

Tipo de bloque desconocido "codeBlock", especifique un serializador para él en la propiedad `serializers.types`.

• Utilice un solo espacio antes y después de los operadores de comparación.

Tipo de bloque desconocido "codeBlock", especifique un serializador para él en la propiedad `serializers.types`.

Las variables suelen representar un estado, así que intenta atribuir nombres claros y descriptivos a sus nombres. A continuación, puede anteponer un verbo a los booleanos para las variables que deben indicar un valor verdadero o falso. A menudo son la respuesta a una pregunta como, por ejemplo, ¿está corriendo el jugador? ¿Se acabó el juego? Añádeles un verbo como prefijo para aclarar su significado. Suele ir acompañado de una descripción o condición, por ejemplo, isPlayerDead, isWalking, hasDamageMultiplier, etc.

Dado que los métodos realizan acciones, una buena regla general es comenzar sus nombres con un verbo y añadir contexto según sea necesario, por ejemplo, GetDirection, FindTarget, etc., en función del tipo de retorno. Si el método tiene un tipo de retorno bool, también puede formularse como una pregunta.

Al igual que las propias variables booleanas, anteponga un verbo a los métodos si devuelven una condición verdadero-falso. Esto los frasea en forma de pregunta, por ejemplo, IsGameOver, HasStartedTurn.

Existen varias convenciones para nombrar los eventos y los manejadores de eventos. En nuestra guía de estilo, nombramos el evento con una frase verbal, similar a un método. Elija un nombre que comunique con precisión el cambio de estado.Utilice el participio presente o pasado para indicar acontecimientos "antes" o "después". Por ejemplo, especifique OpeningDoor para un evento antes de abrir una puerta y DoorOpened para un evento después.

También le recomendamos que no abrevie los nombres. Aunque ahorrar unos cuantos caracteres puede parecer una ganancia de productividad a corto plazo, lo que es obvio para ti ahora puede no serlo dentro de un año para otro compañero de equipo. Los nombres de las variables deben revelar su propósito y ser fáciles de pronunciar. Las variables de una sola letra están bien para bucles y expresiones matemáticas, pero por lo demás, debes evitar las abreviaturas. La claridad es más importante que el tiempo que se ahorra omitiendo algunas vocales.

Al mismo tiempo, utilice una declaración de variable por línea; es menos compacto, pero también menos propenso a errores y mejora la legibilidad. Evite los nombres redundantes. Si tu clase se llama Player, no necesitas crear variables miembro llamadas PlayerScore o PlayerTarget. Recórtalos hasta Score o Target.

Además, evite demasiados prefijos o codificaciones especiales.Una práctica destacada en nuestra guía es anteponer un guión bajo (_) a las variables miembro privadas para diferenciarlas de las variables locales. Algunas guías de estilo utilizan prefijos para las variables miembro privadas (m_), constantes (k_) o variables estáticas (s_), de modo que el nombre revela más sobre la variable.

Sin embargo, es una buena práctica anteponer una "I" mayúscula a los nombres de las interfaces y añadir a continuación un adjetivo que describa su funcionalidad. Incluso puede anteponer "On" al método de activación del evento (en el asunto): El sujeto que invoca el evento suele hacerlo desde un método prefijado con "On", por ejemplo, OnOpeningDoor u OnDoorOpened.

Tipo de bloque desconocido "codeBlock", especifique un serializador para él en la propiedad `serializers.types`.

Las mayúsculas y minúsculas de Camel y Pascal son los estándares de uso común, frente a las mayúsculas de Snake o Kebab, o las notaciones húngaras. Nuestra guía recomienda Pascal case para campos públicos, enums, clases y métodos, y Camel case para variables privadas, ya que es una práctica común en Unity.

Hay muchas normas adicionales que deben tenerse en cuenta fuera de lo que aquí se trata. La guía de ejemplo y nuestro nuevo libro electrónico, Crear una guía de estilo de C#: Escribir código más limpio que escala, proporcionar muchos más consejos para una mejor organización.

El concepto de código limpio pretende hacer más escalable el desarrollo ajustándose a un conjunto de normas de producción. Una guía de estilo debería eliminar la mayoría de las conjeturas que los desarrolladores tendrían que hacer sobre las convenciones que deben seguir. En última instancia, esta guía debería ayudar a su equipo a establecer un consenso en torno a su código base para convertir su proyecto en una producción a escala comercial.

El grado de exhaustividad de su guía de estilo depende de su situación. Tu equipo debe decidir si quiere que su guía establezca normas para conceptos más abstractos e intangibles. Esto podría incluir reglas para usar espacios de nombres, dividir clases o implementar directivas como la directiva #region (o no). Aunque #region puede ayudarle a contraer y ocultar secciones de código en archivos C#, haciendo que los archivos grandes sean más manejables, también es un ejemplo de algo que muchos desarrolladores consideran olores de código o antipatrones. Por lo tanto, es posible que desee evitar el establecimiento de normas estrictas para estos aspectos del estilo del código. No es necesario que todo quede recogido en la guía; a veces basta con debatir y tomar decisiones en equipo.

Cuando hablamos con los expertos que ayudaron a crear nuestra guía, su principal consejo fue la legibilidad del código por encima de todo. He aquí algunos consejos para conseguirlo:

• Utilice menos argumentos: Los argumentos pueden aumentar la complejidad del método. Al reducir su número, los métodos son más fáciles de leer y probar.
• Evita la sobrecarga excesiva: Puede generar una permutación interminable de sobrecargas de métodos. Seleccione los que reflejen cómo llamará al método y, a continuación, impleméntelos. Si sobrecarga un método, evite confusiones asegurándose de que cada firma de método tiene un número distinto de argumentos.
• Evite los efectos secundarios: Un método sólo tiene que hacer lo que su nombre anuncia. Evite modificar cualquier cosa fuera de su ámbito. Siempre que sea posible, introduzca los argumentos por valor en lugar de por referencia. Por lo tanto, cuando envíe resultados a través de la palabra clave out o ref, compruebe que eso es lo que pretende conseguir con el método. Aunque los efectos secundarios son útiles para determinadas tareas, pueden acarrear consecuencias imprevistas. Escriba un método sin efectos secundarios para reducir los comportamientos inesperados.

Esperamos que este blog le ayude a poner en marcha el desarrollo de su propia guía de estilo. Obtenga más información en nuestro archivo C# de ejemplo y en nuestro nuevo libro electrónico, donde podrá revisar nuestras reglas sugeridas y personalizarlas según las preferencias de su equipo.

Los detalles de cada norma son menos importantes que el hecho de que todo el mundo se comprometa a cumplirlas de forma coherente. En caso de duda, confíe en la propia guía evolutiva de su equipo para resolver cualquier desacuerdo de estilo. Al fin y al cabo, se trata de un esfuerzo de grupo.