definicion de estandares y normas de codificacion

,, SS..AA..BB.. DDEE CC..VV. Subdirección de Sistemas Comerciales

EESSTTÁÁNNDDAARREESS DDEE DDEESSAARRRROOLLLLOO CCRRMM

PARA USO INTERNO ÚNICAMENTE/ PROPIEDAD DE TELMEX

ESTÁNDARES DE DESARROLLO CRM

Definición de estándares y normas de codificación.




OBJETIVO .................................................................................................................................................. 3

HERRAMIENTAS RECOMENDADAS .............................................................................................................. 4

DEFINICIONES. ........................................................................................................................................... 6 Definición de estándares generales de codificación. ......................................................................... 6

Definiciones generales de la estructura de los componentes: ........................................................ 10

Definiciones generales de formato para codificación en PHP: ...................................................... 11

Definiciones generales de estructura para codificación en PHP: .................................................. 13

Definiciones generales de interacción con la base de datos para el código en PHP:............ 14

Definiciones generales de formato para codificación en Java Script: ........................................ 15

Definiciones generales de estructura para codificación en Java Script: ..................................... 17

Definiciones generales de interacción entre clases en Java Script: .............................................. 18

Definiciones generales de formato para la creación de objetos en la Base de Datos: .......... 19

CONCLUSIONES: ..................................................................................................................................... 23




Objetivo

Establecer las normas y convenciones necesarias para el desarrollo e integración de módulos y

funcionalidades al sistema CRM para que de esa manera se eleve la calidad, portabilidad,

eficiencia y legibilidad del código.




Herramientas recomendadas

CRM fue creado con la finalidad de integrar la mayor cantidad posible de herramientas

existentes en nuestra empresa que participen directa o indirectamente en la operación,

principalmente los elementos que se encuentren dentro de las fases necesarias desde la labor

de pre-venta hasta la entrega de los servicios y el aseguramiento de los mismos.

De tal manera que para el desarrollo de CRM se eligió una tecnología web que fuese

capaz de integrar a otras herramientas en un mismo ambiente y que además les proporcione

la capacidad de compartir información, ofreciendo así al usuario una interfaz única que le

ayude a agilizar los procesos que hoy realiza, es por esto que se recomienda el uso de las

siguientes herramientas que además de cumplir con estos requisitos permiten la creación de

aplicaciones basadas en un modelo Vista Controlador especialmente para la creación de

nuevos módulos, las herramientas ya existentes deberán en la medida de lo posible adaptarse

a las siguientes definiciones.

Tipo Tecnología Versión Características

Front-End Javascript -

ExtJS 3.3.1 o 4

-Framework muy ligero que permite explotar todas las características de la web 2.0, Ajax, DHTML, DOM, Air, etc. -Proporcionar una gran cantidad de componentes de desarrollo web cada vez más similares a los utilizados en el desarrollo de aplicaciones de escritorio. -Soporta el manejo de información a través de JSON y XML. -Al estar basado en un lenguaje de scripting permite gran control al programador sobre el nivel al que desea programar y especialmente la carga de objetos que tendrá su aplicación, el programador podrá incluso modificar el núcleo del framework a su conveniencia o simplemente utilizar las clases ya definidas.

Back-End

PHP

5 o superior.

-Lenguaje de programación orientado a objetos de libre distribución creado con la finalidad del desarrollo de aplicaciones web dinámicas. -Dentro de las bibliotecas nativas presenta las




librerías necesarias para el trabajo con la gran mayoría de los motores de base de datos existentes. -Expandible, seguro y confiable. -Creado con la finalidad de la creación de aplicaciones web que se adapten a una arquitectura de Modelo Vista Controlador. -De licencia libre.

Base de Datos

Oracle 10g o

superior

-Manejador de base de datos relacional con alta estabilidad y escalabilidad. -Soporte multiplataforma. -Capaz de gestionar grandes cantidades de transacciones y usuarios concurrentes. -Sistema de alta disponibilidad. -Capacidad de ser un sistema distribuido.

El uso de estas herramientas solo es impositivo para la creación de nuevos módulo.




Definiciones.

Definición de estándares generales de codificación.

Definición de nombres:

Todas las aplicaciones y objetos deberán seguir las siguientes definiciones.

Ubicación:

Cada módulo deberá tener su propia carpeta la cual deberá encontrarse dentro de la carpeta de la aplicación a la que pertenece, el nombre de la misma debe ser el título del objeto o aplicación.

Todas las subcarpetas deberán seguir la misma lógica agregando niveles al árbol de archivos.

Referencias:

Todas las referencias entre programas deberán realizarse a través de la nomenclatura de navegación que utilice la herramienta en la cual se desarrollan, esto es se deberá evitar el direccionamiento directo permitiendo a la aplicación la capacidad de transporte sin la necesidad de configuración extra.

Título:

El título de la aplicación u objeto debe iniciar con un acrónimo de 3 letras que identifique el paquete al que pertenece seguidos por un guión bajo y el nombre del componente o modulo utilizando el formato “lower Camel Case”, se recomienda buscar una definición corta y que no exceda las 2 palabras.

Para todos los subcomponentes del módulo se deberá utilizar la misma nomenclatura, siendo el nombre lo más conciso y preciso posible en cuanto a la función del componente.




Se recomienda además dividir los componentes por tecnología utilizada para agilizar su ubicación y facilitar su reutilización.

Ejemplo:




Estructura:

Cabecera:

La cabecera de todos los componentes deberán presentar los siguientes comentarios

dependiendo de la tecnología utilizada será el formato de los mismos, lo importante es que

contengan la siguiente información.

Tipo:

El tipo de componente del que forma parte el encabezado como puede ser módulo,

clase, control, estilo, etc.

Paquete:

Si el componente es parte de una estructura más compleja, como paquetes o

contenedores se deberá nombrar en este campo. Si es necesario mencionar la ruta del

componente o paquete.

Nombre:

El nombre del componente utilizando la nomenclatura utilizada para el nombre del archivo y en formato “lower Camel Case”.

Autor:

El nombre del grupo encargado del desarrollo, como puede ser Mercado Empresarial, EIDON, Blitz, Zentrum, etc.

Versión:

Número de versión del componente.




Fecha:

Fecha de creación del componente. El formato de la fecha debe ser día, mes y año separados por “/”, día y mes deberán expresarse en dos dígitos y año en cuatro.

Descripción:

Enunciado que describa la funcionalidad del componente de la forma más precisa y concisa posible.

Ejemplo de cabecera para un componente en Javascript:




Definiciones generales de la estructura de los componentes:

Debido a que la primera fase de la construcción de CRM se basa principalmente en la integración de diferentes tecnologías se recomienda utilizar el estándar definido generalmente por la empresa desarrolladora de la herramienta para cada una de estas, en este documento solo haremos mención de las convenciones específicas para PHP, JS, EXTJS y Oracle que serán las herramientas utilizadas en la creación de nuevos componentes, sin embargo primero enumeraremos algunas normas que deben ser cubiertas para todas las tecnologías.

Indentación:

Debe permitir identificar a simple vista los diferentes bloques de código que contiene nuestro componente, subrutinas, bloques condicionales, etc. Sin permitir que se confundan con elementos de la misma índole, generando así la cantidad de niveles necesarios, se sugiere que para cada nivel se utilice un espacio igual a un tabulador.

Nombres:

Debido a la diferencia de la notación de las diferentes tecnologías se recomienda apegarse a los estándares establecidos para cada una de las tecnologías para nombrar cada uno de los elementos como son: Clases, objetos, variables, métodos, etc. En caso de no existir una definición clara para algún elemento en específico se utilizará la notación húngara para definir el nombre y utilizando el formato “lower Camel Case”.

Codificación:

Para lenguajes interpretados se debe guardar los archivos en formato ASCII utilizando la codificación ISO-8859-1. Para las demás tecnologías se podrá utilizar cualquier codificación aunque se recomienda ampliamente utilizar la misma que para los lenguajes interpretados.




Definiciones generales de formato para codificación en PHP:

A continuación se detallan las convenciones que deben ser utilizadas para codificar algún componente en PHP:

Bloques PHP:

Evitar en la medida de lo posible incluir bloques PHP dentro de archivos o bloques de código de una tecnología diferente especialmente si estas son client-side. Utilizar AJAX para la comunicación entre las diferentes tecnologías.

Para definir el inicio de un bloque en PHP utilice las etiquetas largas “<?PHP y ¿>” para evitar depender de la configuración del host para el correcto funcionamiento de las aplicaciones.

Comentarios:

Para los comentarios deberá utilizarse el formato de ‘/* y */’ para un bloque o ‘//’ para una línea deberá evitarse el uso de ‘#’.

Inclusiones:

Para incluir un archivo o dependencia deberán utilizarse las instrucciones require_once para cuando se incluya un archivo de configuración que no sea indispensable para la ejecución del módulo e include_once para cuando la inclusión sea indispensable.

Estructuras de control:

Las estructuras de control deberán codificarse sin dejar espacio en blanco desde el keywordy el paréntesis que indica la apertura de las mismas, la llave de apertura deberá de estar en la misma línea.




Namespaces:

Todos los namespaces deberán estar formados por una palabra o iníciales sin puntos entre las mismas en minúsculas, las cuales definan de la forma más precisa el objetivo del namespace.

Clases:

Todas las clases deberán nombrarse utilizando la notación húngara y el formato Upper Camel Case. Deberán expresar de forma precisa el objetivo de la clase y en la mayoría de los casos debería estar formada por una sola palabra.

Funciones:

Las funciones deberán nombrarse utilizando la notación húngara y el formato Lower Camel Case. El nombre deberá expresar de forma concisa la labor de la misma.

Variables:

Las variables deberán nombrarse utilizando la notación húngara y el formato Lower Camel Case. El nombre deberá expresar de forma concisa el objetivo de la misma.




Definiciones generales de estructura para codificación en PHP:

El modelado y programación de las aplicaciones deberá ser orientado a objetos, creando clases que no sean exclusivas del módulo que las implementa si no que puedan convertirse en un componente reutilizable para otros módulos.

Las clases deberán estar en un solo archivo el cual contendrá la definición completa de las mismas, siguiendo las normas de formato descritas en este mismo documento previamente, deben pertenecer a un namespace.

De esta forma no deberá existir código de inicialización o de cualquier otra índole dentro del archivo y fuera de la definición de la clase a menos que este sea parte del proceso nativo de la misma.

La definición de los namespaces deberá coincidir con el árbol de directorios en los cuales se implemente el mismo, ya que esto no contrapone las reglas de formato establecidas y nos ayudan a identificar de manera más ágil cualquier referencia a otras clases, sin necesidad de ubicarla dentro de la documentación.

PHP solo se utilizará del lado del servidor, permitiendo que otras tecnologías de scripting sean las utilizadas para el front-end y harán las llamadas a PHP a través de AJAX. La llamada y respuesta a estos objetos a través de AJAX deberá ser en formato JSON.

Lo más importante de esta estructura es hacer del código lo más legible y reutilizable posible, es importante documentar cada uno de los procesos y registrarlos dentro del namespace permitiendo a otros desarrolladores la utilización de los mismos.

Todas las referencias internas a elementos de la clase deberán hacerse a través del objeto predefinido por PHP $this->evitando el uso de referencias a través del nombre de la clase o la variable del tipo del objeto.




Definiciones generales de interacción con la base de datos para el código en PHP:

Se utilizará la librería Dupral para la interacción entre PHP y la base de datos.

Todos los objetos que utilicen esta librería deberán de cerciorarse que las conexiones a la base de datos sean cerradas después de la última transacción entre PHP y la base de datos, este punto es de suma importancia para evitar bloqueos en la base de datos así como bajo rendimiento en la aplicación.

No se deberán de abrir más conexiones a la base de datos a menos que sea necesario tener diferentes cursores abiertos al mismo tiempo.

Para las llamadas a procedimientos o consultas a la base de datos, la cadena deberá escribirse en mayúsculas entre comillas dobles (“ ”) y utilizando comillas simples (‘ ’) para los valores que tengan relación con un campo en cualquiera de los formatos de texto definidos por la base de datos.

Todas las variables dentro de una consulta o llamada a un procedimiento deberán ser asignadas a la variable en PHP en una sola operación de asignación a menos que el flujo del proceso requiera la concatenación condicional de las instrucciones.

Las variables relacionadas con un campo en cualquiera de los formatos de texto definidos por la base de datos no deberán concatenarse a través del operador de concatenación (.) si no que deberán formar parte de la cadena en una sola asignación.

Para la obtención de valores desde un procedimiento o función desde la base de datos la variable que los recibe deberá ser declarada previamente e igualada a una cadena vacía con el uso de comillas simples (‘ ’) y no a la constante predefinida NULL ni a ningún otro valor como 0 para datos numéricos.

Todas las consultas a la base de datos deberán de presentar el comando AS para definir un alías a los campos obtenidos por las mismas, se evitará el uso del operador * previniendo así que si se presenta un cambio en la base de datos el programa deba ser modificado.

Cualquier operación de INSERT deberá especificar exactamente los campos que se agregarán evitando así que si se presenta un cambio en la base de datos el programa deba ser modificado.

Cuando se utilice una secuencia en cualquier instrucción no se generará un query u operación adicional para obtener el valor de la misma, si no que se integrará dentro de la operación utilizando el comando NEXTVAL.




Definiciones generales de formato para codificación en Java Script:

A continuación se detallan las convenciones que deben ser utilizadas para codificar algún componente en Java Script:

Bloques Java Script:

Evitar en la medida de lo posible incluir bloques Java Script dentro de archivos o bloques de código de una tecnología diferente especialmente si estas son server-

side. Las llamadas a cualquier componente en server-side deberán de ser asíncronas.

Comentarios:

Para los comentarios deberá utilizarse el formato de ‘/* y */’ para un bloque y ‘//’ para una línea.

Inclusiones:

Existirán dos tipos de inclusiones en Java Script, inclusiones realizadas al inicio de la ejecución del componente e inclusiones en tiempo de ejecución.

Las inclusiones que se realicen al inicio de la ejecución del componente deberán realizarse a través de código HTML mediante el tag <SCRIPT>es de suma importancia definir el tipo de script que se está incluyendo, la definición de la fuente no deberá contener la ruta completa del componente si no que deberá acceder al mismo a través de referencias mediante la navegación del directorio valiéndose de los comandos ../ Para subir a través del árbol de directorios y especificando los diferentes directorios para bajar a través de los mismos.

Las inclusiones que se realicen en tiempo de ejecución y que deben utilizarse solo en el caso de componentes que su carga esté condicionada por el flujo del programa y que no sean indispensables en la carga inicial del mismo. Para realizar esta carga se deberá acceder al cabecero del documento HTML e introducir el componente necesario a través de Java Script.




Estructuras de control:

Las estructuras de control deberán codificarse sin dejar espacio en blanco desde el keyword y el paréntesis que indica la apertura de las mismas, la llave de apertura deberá de estar en la misma línea.

Namespaces:

Todos los namespaces deberán estar formados por una palabra o iníciales sin puntos entre las mismas en minúsculas, las cuales definan de la forma más precisa el objetivo del namespace.

Clases:

Todas las clases deberán nombrarse utilizando la notación húngara y el formato Upper Camel Case. Deberán expresar de forma precisa el objetivo de la clase y en la mayoría de los casos debería estar formada por una sola palabra.

Funciones:

Las funciones deberán nombrarse utilizando la notación húngara y el formato Lower Camel Case. El nombre deberá expresar de forma concisa la labor de la misma.

Variables:

Las variables deberán nombrarse utilizando la notación húngara y el formato Lower Camel Case. El nombre deberá expresar de forma concisa el objetivo de la misma.




Definiciones generales de estructura para codificación en Java Script:

El modelado y programación de las aplicaciones deberá ser orientado a objetos, creando clases que no sean exclusivas del módulo que las implementa si no que puedan convertirse en un componente reutilizable para otros módulos.

Las clases deberán estar en un solo archivo el cual contendrá la definición completa de las mismas, siguiendo las normas de formato descritas en este mismo documento previamente, deben pertenecer a un namespace.

De esta forma no deberá existir código de inicialización o de cualquier otra índole dentro del archivo y fuera de la definición de la clase a menos que este sea parte del proceso nativo de la misma.

La definición de los namespaces deberá coincidir con el árbol de directorios en los cuales se implemente el mismo, ya que esto no contrapone las reglas de formato establecidas y nos ayudan a identificar de manera más ágil cualquier referencia a otras clases, sin necesidad de ubicarla dentro de la documentación.

Lo más importante de esta estructura es hacer del código lo más legible y reutilizable posible, es importante documentar cada uno de los procesos y registrarlos dentro del namespace permitiendo a otros desarrolladores la utilización de los mismos.

Todas las referencias internas a elementos de la clase deberán hacerse a través del objeto predefinido por Java Script this evitando el uso de referencias a través del nombre de la clase o la variable del tipo del objeto, es muy importante siempre tener el control del scope de los diferentes elementos. Si es necesario acceder a elementos de un diferente scope del cual nos encontramos parados evitaremos nuevamente las referencias directas en lugar de esto deberemos cambiar el scope actual al scope que necesitamos.




Definiciones generales de interacción entre clases en Java Script:

Para la definición de los parámetros recibidos por las funciones de un objeto deberemos definir dos tipos de parámetros.

Parámetros indispensables:

Parámetros que son indispensables para la ejecución exitosa de la función, estos parámetros deberán definirse de forma explícita en la definición de la función.

Parámetros opcionales:

Parámetros que no son indispensables para la ejecución exitosa de la función pero que su definición modifica el comportamiento de la misma, estos parámetros deberán definirse a través de un solo parámetro el cual será capaz de recibir un arreglo de valores en formato JSON y que podrán ser utilizados dentro de la función.

La respuesta de una función se dará dependiendo del tipo de dato que retorne, en caso de ser un valor se regresará el valor en tal cual sin importar el tipo del mismo ya sea objeto o tipo de dato nativo, si deseamos regresar un conjunto de valores se deberá de hacer a través de un objeto en formato JSON.




Definiciones generales de formato para la creación de objetos en la Base de Datos:

A continuación se detallan las convenciones que deben ser utilizadas para la creación de algún componente en la base de datos:

Tablas:

Las tablas deberán ser nombradas de la siguiente forma: Se antepone el prefijo CRM_ seguido del nombre de la misma el cual deberá reflejar de manera concisa la descripción de los objetos que contiene el cual será definido en plural y se escribirá en mayúsculas, en caso de que sea necesaria más de una palabra para la definición de la misma estas estarán separadas por un guión bajo (_).

Campos:

Antes de definir los campos de una tabla es necesario hacer un análisis completo de los que deberán formar parte de la misma para poder ordenarlos con el siguiente orden de precedencia.

-Índices primarios.

-Índices compuestos.

-Llaves foráneas.

-Campos en orden lógico en base a la definición de los registros.

Los nombres de los campos deben reflejar de forma precisa el dato que contienen, el nombre debe estar formado por un prefijo a tres caracteres del nombre de la tabla seguido por un guión bajo (_), todo esto seguido por el nombre del campo en singular, en caso de ser necesario el uso de más de una palabra estas estarán separadas por un guión bajo (_).




Índices:

Primarios:

El nombre de los índices deberá definirse utilizando el prefijo CRM_IDX_ seguido por el nombre del mismo que describa de forma precisa su objetivo.

Compuestos:

El nombre de los índices deberá definirse utilizando el prefijo CRM_IDC_ seguido por el nombre del mismo que describa de forma precisa su objetivo.

Llaves Foráneas:

El nombre de las llaves foráneas deberá definirse utilizando el prefijo CRM_FK_ seguido por el nombre de la misma que describa de forma precisa su objetivo.

Procedimientos:

Nombre:

El nombre de los procedimientos deberá estar formado por el prefijo CRM_P_ seguido del nombre del mismo que describa de forma precisa la labor del mismo.

Parámetros:

La nombres de los parámetros recibidos por el procedimiento deberán declararse utilizando notación húngara y en mayúsculas, el tipo de dato de los mismos debe ser el más adecuado para el dato que reciben teniendo siempre en cuenta el rendimiento y evitando reservar memoria que no será utilizada.




Variables:

Las variables dentro de un procedimiento deberán nombrarse anteponiendo el prefijo v_ seguidos por el nombre de las mismas el cual se creará utilizando notación húngara y el formato lower Camel Case el tipo de dato de la variable debe ser el más adecuado para el dato que almacena teniendo siempre en cuenta el rendimiento y evitando reservar memoria que no será utilizada.

Estructura:

El código dentro de un procedimiento deberá ser escrito en mayúsculas.

Indentación:

Debe permitir identificar a simple vista los diferentes bloques de código que contiene nuestro procedimiento, subrutinas, bloques condicionales, etc. Sin permitir que se confundan con elementos de la misma índole, generando así la cantidad de niveles necesarios, se sugiere que para cada nivel se utilice un espacio igual a un tabulador.

Funciones:

Nombre:

El nombre de las funciones deberá estar formado por el prefijo CRM_F_ seguido del nombre del mismo que describa de forma precisa la labor del mismo.

Parámetros:

La nombres de los parámetros recibidos por el procedimiento deberán declararse utilizando notación húngara y en mayúsculas, el tipo de dato de los mismos debe ser el más adecuado para el dato que reciben teniendo siempre en cuenta el rendimiento y evitando reservar memoria que no será utilizada.




Variables:

Las variables dentro de un procedimiento deberán nombrarse anteponiendo el prefijo v_ seguidos por el nombre de las mismas el cual se creará utilizando notación húngara y el formato lower Camel Case el tipo de dato de la variable debe ser el más adecuado para el dato que almacena teniendo siempre en cuenta el rendimiento y evitando reservar memoria que no será utilizada.

Estructura:

El código dentro de un procedimiento deberá ser escrito en mayúsculas.

Indentación:

Debe permitir identificar a simple vista los diferentes bloques de código que contiene nuestro procedimiento, subrutinas, bloques condicionales, etc. Sin permitir que se confundan con elementos de la misma índole, generando así la cantidad de niveles necesarios, se sugiere que para cada nivel se utilice un espacio igual a un tabulador

Secuencias:

El nombre de las secuencias deberá estar formado por el prefijo CRM_SEQ_ seguido del nombre del mismo que describa de forma precisa la labor del mismo.




Conclusiones:

Este documento cubre los aspectos básicos e indispensables que son necesarios para la codificación de nuevos componentes a integrar al sistema CRM, el presente no pretende cubrir todos los aspectos involucrados en el desarrollo de los mismos, solo de los más utilizados debido a que por la naturaleza del proyecto esto podría representar un esfuerzo extra el adaptar módulos y sistemas que ya funcionan con diferentes definiciones, cualquier definición no establecida en este documento se deberá utilizar la propuesta por el proveedor de la tecnología en cuestión y apegarse a las normas de programación que el mismo propone.

La aplicación de estas nos permitirá obtener un software que pueda ser reutilizado y expandible, ya que podrá ser interpretado por cualquier otro desarrollador que se interese en el mismo.

Es de suma importancia que todos los grupos involucrados tengan siempre presente que el objetivo final es entregar un software de calidad que cumpla con la mayor cantidad de estándares y normas no solo en la codificación sí no también en la administración de recursos, la interacción con el usuario, la fiabilidad y expansibilidad del mismo.




ANEXO 1.

Tabla de notación húngara sugerida.

Por alcance:

Alcance Notación

Local l

Privada p

Global g

Parámetro t

Por tipo:

Tipo Notación

Arreglo a

Carácter c

Moneda y

Fecha d

Fecha y Hora t

Doble b

Flotante f

Lógico l

Numérico n

Objeto o

Desconocido u

definicion de estandares y normas de codificacion

Documents