Este documento pretende dejar claro las reglas de pensamiento para el desarrollo. Indice MODELO HUMANO DE LA EMPRESA Y MODELO VIRTUAL LENGUAJE EN MODELOS Y VARIABLES NAMING CODE LOGS -------------------------------------------------------------------------------- MODELO HUMANO DE LA EMPRESA Y MODELO VIRTUAL El modelo virtual, en lo que refiere a dominio, debería ser un representación o espejo fideligno al modelo humano. Esto es para hacer más sensillo su entendimiento y mantenimiento. -------------------------------------------------------------------------------- LENGUAJE EN MODELOS Y VARIABLES Decidí usar todo en español. Ya que este proyecto será desarrollado por personas de habla hispana, y seguramente continuará su evolución de la misma manera. Utilizar inglés podría acarrear dudas en el naming de los componentes, y obligaría a una traducción mental todo el tiempo. No obstante, algunas clases que son o podrían ser clases compartidas con otros proyectos, podrían estar en inglés. -------------------------------------------------------------------------------- NAMING - El equipo o el desarrollador debe homogenizar las palabras a utilizar, esto incluye al idioma y al sinónimo para cada operación: Alta: alta / agregar / add Baja: baja / borrar / eliminar / quitar etc Y puede haber una diferencia entre que palabra se usa en el dialógo de desarrollador, y las palabras a usar para comunicar con el usuario, ya que pueden ser más comúnes. - Preferencia por uso de SINGULAR. - Ñ: se reemplaza con "ni", ejemplo: anio, cumpleanios, etc. - Separación de palabras: Se prefiere el uso de "_" en lugar de "-". Y para evitar confusiones, hacer que esa separación sea absolutamente para todo ámbito. Algunos sistemas de archivos y servidores web pueden interpretar el guion medio como un carácter especial, lo que podría causar problemas en la manipulación de archivos o URLs. Por ejemplo, en algunos sistemas de archivos, el guion medio puede indicar un rango de caracteres, y en URLs, puede considerarse un carácter separador. Esto podría llevar a comportamientos inesperados o errores. A su vez, javascript, podría confundir con una resta. CLASSES Siempre son sustantivo. METHODS y ACTIONS Siempre son verbos. PROTECTED Naming normal, sin prefijo "_" PRIVATE Usan prefijo "_" COLLECTIONS NO SE. DUDAS CON ESTE PUNTO. Terminarán con "_col" INTERFASES NO SE. DUDAS CON ESTE PUNTO. Habitualmente comienzan con una "I", pero he visto que Laravel utiliza alias terminando en "Contract", y me gusta. Desarrollaré con esa nomenclatura. VARIABLES General Usan CamelCase Cuando refieren a campos de una tabla de la BD Usan el mismo nombre, incluso la palabra separada por '_' (snake case). ARRAYS Terminarán con "Array" NO SE. DUDAS CON ESTE PUNTO. Un array de objetos podría ser "Rendicion_array" KEYS EN ARRAYS ASOCIATIVOS Siempre en minúscula por más que contengan un objeto y quiera indicarse su class. Preferencia por uso de snake case. CONSTANTES En mayúsculas y separando palabras con "_" (snake case). Para datos o palabras que pudieran estar presentes en todo el proyecto, es mejor definirlos como constantes o globales, y no asignar valores directamente a la variable: $state = '1'; // NO ! $state = STATE_ACTIVE; // SI ! Así será fácil encontrarlos en cualquier fuente. Ejemplo: Constantes definidas para todo proyecto: ID_USUARIO CLIENTE_APROBADO Constantes definidas dentro de la clase: $tipoDeCliente = self::CLIENTE_TIPO; BASE DE DATOS Tablas Tabla En plural, todas sus palabras, en snake case. Prefijos para indicar a que modulo pertenece. Por ejemplo: "usu_" módulo de usuarios "cli_" módulo de clientes Con dos o mas palabras La primera palabra es el objeto o prioridad. Campos En singular. Tablas de relación Usan el prefijo "rel_" Use ambos nombres de las tabla relacionados, separados con "_" Ejemplo: rel_facturas_productos ( factura => productos ) Campos: tableName en singular + "_id" (excepto los campos que ya vienen usados en Zend, mantendré el nombre, ej: sedes_id ) Si el campo original tiene otro nombre, en la tabla relacionada lo seguiré referenciando como "_id". usuario_id ( en la original podría llamarse "dni" ) factura_id ( en la original podría llamarse "numero" ) producto_id Índices Comienza con "i_" + nombre de tabla + índice de campos Enumera los campos que los compone, separados con "_" Ejemplo i_usuario_apellido ( tabla: usuario, campo: apellido ) Unique Comienza con "u_" + nombre de tabla + índice de campos Foreing index Comienza con "fk_" + nombre de tabla 1 + "_TO_" + nombre de tabla 2 FRONT HTML Nombres en modo snake. CSS Nombres en modo snake. JAVASCRIPT Dado que es programación, utilizar el mísmo modo de escritura, que en el lenguaje para servidor (php u otro). -------------------------------------------------------------------------------- CODE CONTROLLERS Los controllers estarán vacíos de lógica. Solo reciben la solicitud url, utilizan un caso de uso, y asignan una respuesta de pantalla. No usan ni necesitan metódos privados. Siempre serán públicos. -------------------------------------------------------------------------------- LOGS El objetivo común de los logs es informar el resultado de un proceso. Saber si ha llegado hasta el final, o ha ocurrido un error durante. Cuanto más preciso sea la información, mejor. Si indica que simplemente termino bien, en algunos casos nos faltará información que pudiera ser más informativa. Por ejemplo, si un proceso incorpora pagos, saber que pagos se incorporaron sería muy relevante si aparece un reclamo de un pago no incorporado. A su vez, informar que un pago fue rechazado y no conocer el motivo, deja el trabajo de búsqueda al desarrollador. Indicar palabras clave de alerta dentro del log facilitará su examen. Repetir la misma información en cada corrida, tenderá a que el log sea ignorado. Por lo que es importante evitar informar sobre los mismos elementos en cada log. El log suma información, si nos dice que elemento nuevo fue incorporado o rechazado. y luego, no repetir esa data en el siguiente log. Pero trabajar de esta forma, necesita que los logs, con rechazos o errores, sean informados y revisados manualmente con urgencia. Estos logs, que tienen información valiosa, deben entonces, perdurar un tiempo prudencial, para permitir que sean revisados manualmente. Podría ser por tiempo de una semana o un mes si fuere el modo de rutina de trabajo.