Pautas y convenciones para Code QA: Naming & Casing (II)

En este artículo vamos a adentrarnos en uno de los puntos que presentamos dentro de las pautas y convenciones para CodeQA en el anterior artículo. Así pues, trataremos el naming (nombramiento) de ficheros y su contenido, y los distintos tipos de casing (combinación de mayúsculas y minúsculas) que deberíamos usar en la creación del fichero o durante su desarrollo.

Tal y como lo hemos establecido en SogetiLabs Spain, situándonos en el contexto que planteábamos en la introducción de esta serie, este punto también nos ayuda en el proceso de creación de valor en equipos multidisciplinares. En concreto, nos facilita la identificación de cada tipo de archivo y el lenguaje en el que está escrito para así poder centrarnos en su comprensión.

Sea cual sea tu perfil, seguro que a diario debes tratar con archivos de código, de texto, multimedia, y otros assetsen tu proyecto, todos ellos agrupados por carpetas o paquetes. Luego, por ejemplo, dentro de cualquier fichero de programación habrá nomenclatura concreta como clases, métodos o funciones, variables y constantes. En definitiva, todos estos archivos y vocabulario en el caso de código deben tener un nombre único que los identifique. Es importante que el nombre escogido sea lo suficientemente representativo como para que tus compañeros o tú mismo en un futuro podáis centraros en deducir su lógica en el código o, en el caso de un fichero, su contenido.

Por otro lado, además del significado que nos transmite el propio nombre, la forma en la que esté escrito nos ayudará a identificar rápidamente qué tipo de archivo es o qué lenguaje de programación contiene o estamos leyendo. Existen múltiples tipos de formas o casings, pero a continuación mostramos los más conocidos en la forma en la que se escriben:

• camelCase: Sin separaciones y en minúscula excepto la inicial de cada palabra, salvo la primera.
• PascalCase: Sin separaciones y en minúscula excepto la inicial de cada palabra.
• snake_case: Palabras separadas por guiones bajos (o barras bajas) y en minúscula.
• SCREAMING_SNAKE_CASE: Variante en mayúscula del snake_case.
• kebab-case: Palabras separadas por guiones altos y en minúscula.
• dot.case: Palabras separadas por puntos y en minúscula.

Hay que tener en cuenta que muchos lenguajes de programación ya tienen su casing predeterminado por convención de la comunidad o de los propios desarrolladores del lenguaje, por eso recomendamos seguir siempre el indicado. Así pues, las especificaciones en este artículo son las que aplicamos en SogetiLabs Spain para homogeneizar el naming y casing para cada lenguaje o, siempre que las reglas nativas ya establecidas lo permitan, para múltiples lenguajes.

A continuación, iremos asociando el casing adecuado para cada tipo de archivo o contenido, e indicando algunas recomendaciones para mejorar el proceso de naming.

• Archivos de texto plano o enriquecido y archivos multimedia
  • Naming: Lo más claro y conciso posible. Si contiene algún número identificador o fecha recomendamos ponerlo al inicio para facilitar su ordenación e identificación en los sistemas de ficheros (e.g. icon_RGB.png, 31122019_nombre_del_documento.docx).
  • Casing: snake_case.
• Archivos de configuración, entorno o propiedades (.yml, .json, .env, .properties…)
  • Naming: Una o dos palabras como máximo que definan su scope de configuración (web, service, app, project, …) o el entorno para el que aplican (development, acceptance, production, …). Preferiblemente que no se modifique en el tiempo para evitar confusión o desconfiguración del proyecto (e.g. app-dev.properties).
  • Casing: kebab-case.
  • Contenido: Depende del tipo de archivo, pero lo más común es usar en las claves dot.case para YAML, snake_case o SCREAMING_SNAKE_CASE para ENV o PROPERTIES, y camelCase o PascalCase para JSON.
• Carpetas, Packages o Namespaces
  • Naming: Una sola palabra que defina el tipo de archivos que contiene o su función en el proyecto (e.g. services, middleware)
  • Casing: En caso de una sola palabra, en minúscula. Si se necesitan múltiples palabras se recomienda crear subcarpetas o subniveles usando dot.case en el caso de packages o namespaces (e.g. controllers.main).
• Clases, Structs
  • Naming: Un nombre en singular tan conciso como sea posible, nunca un verbo (e.g. UserProject, Sizes).
  • Casing: PascalCase.
• Métodos/Funciones
  • Naming: Un predicado tan conciso como sea posible, donde el verbo suele estar en infinitivo (e.g. calcularTiempoRestante()).
  • Casing: Según el lenguaje.
    • Java/C/C++/PHP/JS: camelCase.
    • C#/Visual Basic/R: PascalCase.
    • Python: snake_case.
• Variables (Locales y Argumentos/Parámetros)
  • Naming: Un nombre autoexplicativo y que sea relacionable con el tipo de datos que representa (e.g. projectsList, wordCount).
  • Casing: Según el lenguaje.
    • Java/C/C++/C#/Visual Basic/PHP/JS: camelCase.
    • Python/R: snake_case.
• Constantes, Variables Globales y Enumeraciones
  • Naming: Igual que las variables (e.g. PI_NUMBER, MACHINE_STATE_OFF).
  • Casing: SCREAMING_SNAKE_CASE.
    • En JS, si usa la palabra reservada const se permite camelCase.
• IDs de HTML y Clases CSS
  • Naming: Igual que las variables (e.g. user-email, black-box).
  • Casing:
    • IDs de HTML: Preferentementekebab-case, pero también se suele aceptar camelCase para diferenciarlos de las clases CSS. En cualquier caso, se debe mantener el mismo casing para todos los ficheros HTML en el proyecto, asegurando así la consistencia y evitando confusión.
    • Clases CSS: kebab-case. Aunque también usamos la notación block__element–modifier (BEM) (e.g. header__menu-item–dark).
• Endpoints de API REST y paths, parámetros de query y fragmentos de URI
  • Naming:
    • Endpoints de API REST, paths y fragmentos: Igual que las variables, pero una única palabra o múltiples abreviadas siempre que sea posible (e.g. /load-user, /admin-page, #author-bio).
    • Parámetros de query: Igual que las variables, pero abreviados a solamente las iniciales del parámetro cuando la query tenga múltiples parámetros (e.g. user-id=1234 à uid=1234).
  • Casing: kebab-case.

Con estas recomendaciones hemos cubierto el primer punto de las pautas y convenciones para CodeQA. Esta vez hemos visto la importancia de nombrar (naming) lo más conciso y preciso posible a nuestros ficheros y palabras clave en nuestro código, para comprender mejor lo que representan. Además, usando la combinación de separadores, mayúsculas y minúsculas (casing) adecuada podemos identificar el tipo de archivo que son o el lenguaje de programación en el que están escritos.

Seguiremos tratando nuevos temas sobre CodeQA en el siguiente artículo, donde hablaremos sobre la documentación del código, que incluye la redacción de comentarios, documentación API del lenguaje, y anotaciones. ¡Os esperamos!