Solo hay dos cosas difíciles en informática: invalidación de caché
y nombrar cosas.
- Phil Karlton
Nosotros, los desarrolladores, pasamos más tiempo leyendo códigos que escribiéndolos. Es importante que el código sea legible y claro sobre su intención.
A continuación hay algunos consejos basados en mi experiencia al nombrar cosas.
Significado
Un nombre, ya sea una variable, una propiedad, una clase o una interfaz, debe reflejar el propósito de por qué se introduce y cómo se usa.
Usa nombres precisos
Si uno no puede tener una idea sobre el uso y el propósito sin comentarios adicionales, el nombre no es lo suficientemente bueno. Si el uso inmediato o la idea de propósito basada en la denominación es incorrecta, entonces la denominación es inaceptable.
El peor nombre posible es cuando el nombre de un método le corresponde al que lo lee.
Evita nombres sin sentido
Estos son nombres como $i , $j , $k etc. Si bien estos están bien para usar en ciclos, en otros casos están desperdiciando la legibilidad.
Una fuente común de tales nombres es la ciencia clásica, donde la mayoría de las fórmulas usan variables de una letra, por lo que es más rápido escribir. Como consecuencia, no puede dar sentido a estas fórmulas sin un párrafo introductorio que explique la denominación. A menudo este párrafo es difícil de encontrar.
Dado que la educación en ciencias de la computación incluye un número significativo de disciplinas de ciencias clásicas, los estudiantes se están acostumbrando a tales nombres y los llevan a la programación.
Nombrar clases, interfaces, propiedades y métodos
El nombre de la clase debe ser uno o varios sustantivos. No debería haber verbos. Intente evitar "datos", "administrador", "información", "procesador", "manejador", "fabricante", "util", etc. ya que estos suelen ser un indicador de nombres imprecisos.
Las interfaces suelen ser sustantivos o adjetivos. Algunos equipos, incluido PHP-FIG , optaron por fijar las interfaces con la Interface . Algunos lo hacen con el prefijo I y otros no usan prefijo ni postfix. Creo que todo esto es aceptable en caso de que sea consistente.
Las propiedades deben nombrarse con sustantivos o adjetivos. Para los booleanos, use frases afirmativas con el prefijo "Is", "Can" o "Has" cuando corresponda.
Los nombres de los métodos deben contener uno o más verbos, ya que son acciones. Elija un verbo que describa lo que hace el método, no cómo lo hace.
Si bien no es estrictamente necesario, es una buena idea finalizar el nombre de la clase derivada con el nombre de la clase base:
class Exception {} class InvalidArgumentException extends Exception {}
Consistencia
Use un solo nombre para un solo concepto. Se consistente.
Un buen ejemplo es usar begin / end todas partes en lugar de mezclarlo con start / finish .
Siga las convenciones de estilo de código
Al desarrollar un proyecto, un equipo debe acordar el estilo de código y las convenciones de nomenclatura que usan y seguirlas. Si una parte de las convenciones no es aceptada por algunos miembros del equipo, debe revisarse, modificarse y establecerse una nueva regla.
Para PHP, la convención más común es actualmente PSR-2 y la mayoría de las convenciones internas de proyectos se basan en ella.
Verbosidad
Evite reutilizar nombres
El uso del mismo nombre para muchos conceptos debe evitarse si es posible, ya que trae dos problemas:
- Al leer, debes tener en cuenta el contexto. Por lo general, eso significa llegar al espacio de nombres o la declaración del paquete constantemente.
- Buscar esos nombres es un dolor.
Evitar contracciones
No use contracciones. Ejemplos comunes son:
function cntBigWrds($data, $length) { $i = 0; foreach ($data as $iter) { if (mb_strlen($iter) > $length) { $i++; } } return $i; } $data = ['I', 'am', 'word']; echo cntBigWrds($data, 3);
El código anterior cuando se nombra correctamente se convierte en:
function countWordsLongerThan(array $words, int $minimumLength) { $count = 0; foreach ($words as $word) { if (mb_strlen($word) > $minimumLength) { $count++; } } return $count; } $words = ['I', 'am', 'word']; echo countWordsLongerThan($words, 3);
Tenga en cuenta que los nombres explicativos cortos sin contracciones son mejores que los nombres explicativos largos, así que no tome la verbosidad al extremo y termine con nombres como processTextReplacingMoreThanASingleSpaceWithASingleSpace() .
Si el nombre es demasiado largo, significa que podría modificarse para acortarlo o que lo que está nombrando está haciendo demasiado y debe refactorizarse en varias cosas.
Evitar siglas
Evite siglas y abreviaturas, excepto las comúnmente conocidas como HTML. Elon Musk envió un correo electrónico titulado "Acrónimos en serio" a todos los empleados de SpaceX en mayo de 2010:
Hay una tendencia progresiva a usar siglas inventadas en SpaceX. El uso excesivo de siglas inventadas es un impedimento significativo para la comunicación y mantener una buena comunicación a medida que crecemos es increíblemente importante. Individualmente, algunos acrónimos aquí y allá pueden no parecer tan malos, pero si miles de personas los inventan, con el tiempo el resultado será un enorme glosario que tenemos que emitir a los nuevos empleados. Nadie puede recordar todos estos acrónimos y las personas no quieren parecer tontas en una reunión, por lo que simplemente se sientan allí en la ignorancia. Esto es particularmente difícil para los nuevos empleados.
Eso debe detenerse de inmediato o tomaré medidas drásticas: he dado suficiente advertencia a lo largo de los años. A menos que yo apruebe un acrónimo, no debe ingresar al glosario SpaceX. Si hay un acrónimo existente que no puede justificarse razonablemente, debería eliminarse, como lo solicité en el pasado.
Por ejemplo, no debe haber designaciones "HTS" [banco de pruebas horizontal] o "VTS" [banco de pruebas vertical] para bancos de pruebas. Esos son particularmente tontos, ya que contienen palabras innecesarias. Un "stand" en nuestro sitio de prueba es obviamente un banco de pruebas. VTS-3 son cuatro sílabas en comparación con "Tripod", que son dos, por lo que la versión de acrónimo sangriento en realidad toma más tiempo para decir que el nombre.
La prueba clave para un acrónimo es preguntar si ayuda o perjudica la comunicación. Un acrónimo que la mayoría de los ingenieros fuera de SpaceX ya conoce, como GUI, está bien para usar. También está bien inventar algunos acrónimos / contracciones de vez en cuando, suponiendo que los haya aprobado, por ejemplo, MVac y M9 en lugar de Merlin 1C-Vacuum o Merlin 1C-Sea Level, pero esos deben mantenerse al mínimo.
Estoy de acuerdo con el
Legibilidad
El código debería poder leerse tan fácilmente como la prosa. Elija las palabras que elegiría para escribir un artículo o un libro. Por ejemplo, una propiedad llamada TotalAmount es más legible en inglés que AmountTotal .
Ocultar detalles de implementación
Se trata más del diseño orientado a objetos, pero afecta mucho la legibilidad si se exponen los detalles de implementación. Trate de no exponer métodos nombrados como:
initializeinitcreatebuild
Lenguaje de dominio
El código debe usar los mismos nombres que los utilizados en el modelo de negocio o dominio automatizado.
Por ejemplo, si una empresa de viajes usa "lugar" como nombre general para cafeterías, hoteles y atracciones turísticas, es una mala idea usar "lugar" en el código porque usted y sus usuarios hablarán dos idiomas diferentes, lo que lo hace más complicado. de lo que debería.
Tal lenguaje a menudo se llama "El lenguaje ubicuo". Puede obtener más información del mini libro " Diseño impulsado por dominio rápidamente " de InfoQ.
Ingles
La mayoría de los lenguajes de programación usan el inglés para construcciones integradas y también es una buena práctica nombrar las cosas en inglés. Es extremadamente importante para un desarrollador aprender inglés al menos en el nivel básico y, lo que es más importante, tener un buen vocabulario que uno pueda usar para encontrar un buen nombre.
Algunas herramientas útiles:
Referencias