Nomenclaturas

Es importante definir una manera concisa de nombrar nuestras variables, funciones, clases, métodos, etc. No existe una regla general de cómo hacerlo; de hecho, para algunos, es la parte más difícil de escribir código. Sin embargo, existen algunas convenciones que nos pueden ayudar a dar con el nombre perfecto para nuestras piezas básicas del código.

Generalidades

Idioma

Resulta importante definir que TODO código que escribamos para Mindsight debe ser escrito en inglés. Más que nada para estandarizar términos, facilitar la lectura y evitar confusiones.

Case

El case que se ultiliza para dar nombre a nuestras variables, funciones, clases, métodos, etc. depende del lenguaje que estemos utilizando. Para cada lenguaje que utilicemos en Mindsight, definiremos la convención de case que se debe utilizar en la sección correspondiente de esta documentacion.

Nombres descriptivos:

Los nombres de las variables, funciones, clases, métodos, etc. deben ser descriptivos y representar el propósito de la pieza de código que estamos escribiendo.

Por ejemplo, si tenemos una variable que almacena el estado actual del clima, dependiendo del caso, podemos definir los siguientes nombres para dicha variable:

// Un ejemplo genérico de un buen nombre para la variable
const currentWeather = 'sunny';
 
// Si es que se trabaja con un identificador de clima
const currentWeatherId = 1;
 
// Si es que se necesita especificar que se trata de un nombre
const currentWeatherName = 'sunny';
 
// Si es que trabajamos con una estructura que representa el clima
const currentWeatherData = {
  id: 1,
  name: 'sunny'
};

Ahora, veamos ejemplos de nombres no tan buenos para este caso:

// No nos dice mucho sobre el propósito de la variable
const weather = 'sunny';
 
// Si es que trabajamos con lenguajes que son tipados, esto resulta 
// redundante y no agrega información valiosa ni descriptiva 
const weatherNumber = 1;
 
// Este ejemplo se explica solo
const w = 'sunny';
 
// Bro...
const dog = {
  id: 1,
  name: 'sunny'
};

Tipos

El nombramiento de nuestros objetos depende en la mayoria de los casos de su tipo especifico. A continuacion se presentan algunas convenciones generales para nombrar objetos de diferentes tipos:

Funciones

Por lo general, las funciones deben incluir algun verbo que nos indique la accion que realiza. Por ejemplo:

// Simple y conciso, una funcion que añade dos numeros
const addTwoNumbers = (a: number, b: number) => a + b;
 
// Esta funcion nos indica que se realiza un fetch de un usuario por su ID
const fetchUserById = (id: number) => {
  // ...
};
 
// Esta funcion debe revisar si un usuario es administrador
const checkIfUserIsAdmin = (user: User) => {
  // ...
};

Contraejemplos de esto serian:

// Ok, esta funcion añade, pero no indica q se limita a dos numeros
const add = (a: number, b: number) => a + b;
 
// Aqui para utilizar la funcion correctamente dependemos de revisar su firma
const fetchUser = (id: number) => {
  // ...
};
 
// El nombre indica una condicion, no una accion, 
// podria confundirse con un booleano
const isUserAdmin = (user: User) => {
  // ...
};

Booleanos

Las variables booleanas deben partir con alguna palabra clave que indique semanticmaente que se trata de una condicion, por ejemplo:

const isOpen = true;
 
const doesUserHaveLicense = true;
 
const canUserDrive = true;

Otros

Existen ciertas nomenclaturas basadas en tipos de objetos que son comunes en la mayoria de los lenguajes de programacion. Por ejemplo, en TypeScript, es comun utilizar los prefijos I para interfaces, T para tipos genericos, E para enumeraciones, etc.

Estas convenciones no siempre son obligatorias y dependen del lenguaje en especifico que se esta utilizando. En Mindsight definieremos estas convenciones para cada lenguaje que utilicemos en su seccion propia dentro de esta documentacion.

Distinciones, consistencia y conceptos

Se debe tratar de lograr una distincion clara y una consistencia en como nombramos las variables dentro del ocntexto de negocio de nuestro codigo.

Por ejemplo podriamos estar desarrollando una aplicacion que maneja dinero en distintas monedas:

// Estas variable tienen nombres descriptivos
// pero no tiene una distincion dentro del contexto
// 1000 dolares? 1000 pesos? 1000 euros?
const moneyAmount = 1000;
const todayMoney = 1000;
const customerMoney = 1000;
 
// Estas variables se entienden mucho mejor
const moneyAmountInUsd = 1000;
const moneyAmountInClp = 10000;
const moneyAmountInEur = 100000;
 
// Aunque esta variable es descriptiva, no sigue la convencion
// de las otras variables en cuanto a los conceptos que se usan
const moneyInPesos = 10000; // no se usa el concepto "Amount"
const currencyAmountinUsd = 1000; // no se usa el concepto "Money"
const cashQuantityInEur = 100000; // se cambian los conceptos por completo

De esto ultimo tambien desprendemos que debemos utilizar una misma palabra para referirnos a un mismo concepto. Por ejemplo, si estamos trabajando con usuarios, podemos referirnos a ellos como user, pero no cambiar posteriormente a client, customer, person, etc.

Redundancia

La redundancia en los nombres de nuestros objetos es algo que debemos evitar. Por ejemplo, si estamos trabajando con un objeto que representa un usuario, no es necesario que sus propiedades indique que son del usuario:

// Propiedades redundantes
const user = {
  userId: 1,
  userName: 'John Doe',
  userEmail: '...'
};
 
// Por el contrario, un objeto con propiedades bien descritas 
const user = {
  id: 1,
  name: 'John Doe',
  email: '...'
};

Otros ejemplos de redundancia podrian ser cuando se trabaja dentro de un lenguaje tipado, por ejemplo:

// Redundancia en el nombre del objeto
const userNameString: string = 'John Doe';
const userAgeNumber: number = 30;
const getUserByIdFunction: Function = (id: number) => {
  // ...
};

Pronunciabilidad y Abreviaciones

Los nombres de variables deben ser pronunciables y buscables, asi evitamos confusiones, mejoramos la legibilidad y permitimos que otros puedan entender y navegar nuestro codigo facilmente.

Si no puedes pronunciar el nombre de una variable, probablemente no sea un buen nombre. Por ejemplo:

// Usuario? Union Sovietica?
const usrDetails = { /*...*/ }
 
// Se entiende que es un timestamp, pero dificulta la lectura y
// su busqueda en el codigo
const currentTmpStmp = new Date();
 
// Que es un zxcvb?, como se pronuncia?, esto es un ejemplo de un pesimo nombre para una variable.
const zxcvb = 'hola'