LINEAMIENTO PARA DESARROLLO DE APLICATIVOS EN C#

Transcripción

1 Bogotá D.C., Julio 2014

2 TABLA DE CONTENIDO 1. OBJETIVO ALCANCE TERMINOS Y DEFINICIONES BUENAS PRÁCTICAS EN NOMENCLATURA INDENTACIÓN, ESPACIADO Y AGRUPACIÓN DE CÓDIGO COMENTARIOS TESTING UNITARIO PLATAFORMA DESARROLLO MARCO LEGAL REQUISITOS TÉCNICOS DOCUMENTOS ASOCIADOS RESPONSABLE DEL DOCUMENTO

3 1. OBJETIVO Este documento describe los estándares y lineamientos de codificación que son establecidos para la elaboración e interpretación de programas escritos en el lenguaje de programación, que son desarrollados por el Área de Información y Sistemas del Departamento Administrativo de la Presidencia de la República aplicando las mejores prácticas y la normatividad vigente. 2. ALCANCE Los lineamientos aplican para el desarrollo de aplicativos en el lenguaje de programación orientado a objetos, desarrollado y estandarizado por Microsoft, al interior del Departamento Administrativo de la Presidencia de la República y debe ser acogido por el Área de Información y Sistemas. 3. TERMINOS Y DEFINICIONES Assembly: se refiere a uno a más archivos que son la salida de la compilación de un programa. Fuente de esta información. AssemblyInfo: se refiere aun a clase que provee atributos para obtener información sobre el programa, tal como número de versión, descripción, etc. Fuente de esta información. Bases de datos: Se refiere a un conjunto de datos o archivos que tiene una estructura en común, la cual está organizada de tal forma que el ordenador pueda fácilmente encontrar la información. Camel Casing: Se refiere a guías de nomenclatura de código fuente. Fuente de esta información. : Es un lenguaje de programación orientado a objetos, desarrollado y estandarizado por Microsoft, forma parte de la plataforma.net. Fuente de esta información. Excepción: Se refiere a la indicación de un problema en la ejecución de un programa desarrollado, es poco frecuente, pero es importante contar con un manejo adecuado de estas. Fuente de esta información. Indentación: Se refiere a mover un bloque de texto hacia la derecha con espacios o tabulaciones para distinguirlo del texto adyacente. Fuente de esta información. 3

4 keyword internal: Se refiere a una palabra clave que referencia a un modificador de acceso a los tipos y miembros de una clase que pertenecen a un mismo conjunto de Librerías y clases. Fuente de esta información. Loop: se refiere a un bucle de programación. Fuente de esta información. Namespace: Se refiere a un sistema de organización lógico que proporciona una forma de presentación de los elementos del programa que son expuestos hacia otros. Fuente de esta información. Namespace System: Se refiere a un sistema de organización lógico que contiene clases base que definen tipos de datos de uso común, eventos, controladores de eventos, interfaces, atributos y excepciones de procesamiento. Fuente de esta información. Pascal Casing: Se refiere a guías de nomenclatura de código fuente. Fuente de esta información. String: Tipo de dato que representa una serie de caracteres Unicode. Fuente de esta información. String.Equals: Se refiere a un método que determina si dos cadenas de texto tienen el mismo valor. Fuente de esta información. String.Empty: Se refiere a un método que representa una cadena de texto vacía. Este campo es de solo lectura. Fuente de esta información. StringComparison: se refiere a un método de tipo enumerador, el cual es utilizado para especificar si la comparación de una cadena de texto debe usar la referencia actual cultural, palabras o reglas de ordenación, y distinción entre mayúsculas o minúsculas. Fuente de esta información. StringBuilder: Se refiere a una clase que representa una cadena de texto como un objeto. Fuente de esta información. Sockets: Se refiere a un método para la comunicación entre un programa de cliente y un programa del servidor en una red. Fuente de esta información. Streams: Se refiere a una técnica para transferir datos que pueden ser procesados como un flujo regular y continuo. Fuente de esta información. 4

5 Throw: Se refiere a la palabra clave (Keyword Internal), que se utiliza para señalar la aparición de una situación o evento anómalo durante la ejecución de un programa. Fuente de esta información. Unicode: se refiere a un estándar de codificación de caracteres con la intención de representar texto de múltiples lenguajes, el término Unicode proviene de las palabras: universalidad, uniformidad y unicidad. Fuente de esta información. Using: Se refiere a la palabra clave (Keyword Internal) la cual permite el uso de tipos en un espacio de nombres (namespace). Fuente de esta información. 4. BUENAS PRÁCTICAS EN Con el fin de establecer buenas prácticas en el desarrollo de aplicativos para el DAPRE se establecen los siguientes lineamientos para la aplicación de los mismos: 1.En : Utilizar tipos específicos de (alias) en lugar de los tipos definidos en el namespace System. 2. Para comparar dos strings se debe utilizar el String.Equals pasándole cómo parámetro el StringComparison para evitar diferencias entre mayúsculas y minúsculas, así como también las diferentes culturas. 3. Utilizar String.Empty en lugar de utilizar el carácter de comilla doble. 4. Evitar métodos y propiedades públicas, a menos que sea estrictamente necesario accederlas desde afuera de la clase. Utilizar el keyword internal si estos miembros deben ser accedidos desde dentro del mismo assembly. 5. Utilizar el archive AssemblyInfo para completar información como Número de versión, Descripción, Compañía, Copyright, etc. 6. Al abrir conexiones a bases de datos, Sockets, Streams, etc. siempre cerrarlos en los bloques finally. Esto asegurará que aún ante la eventualidad de una excepción, estos accesos serán cerrados. Se puede usar el using en caso de no tener que capturar una excepción en particular dentro del catch. 7. La declaración de las variables locales de un método, deberá realizarse en el bloque superior de éste. Todas las variables deben estar declaradas en el mismo lugar y deben ser inicializadas para limpiar su valor predeterminado. 5

6 8. Utilizar la clase StringBuilder en lugar de String cuando sea requerido manipular cadenas en loops y en operaciones de concatenación intensivas ya que éste reporta una mejor performance. En caso de tratarse de concatenaciones simples, utilizar String.Concat. 9. Utilizar el largo de cadenas para determinar si éstas son vacías, en lugar de realizar una comparación con una cadena vacía. Si la variable puede tener el valor null, es posible también utilizar el método String.IsNullOrEmpty para realizar esta verificación. Ejemplo: Uso del método IsNullOrEmpty. if ( String.IsNullOrEmpty(customerName)) 10. En casos de excepción, se debe mostrar un mensaje amigable al usuario, obteniendo la excepción con todos los detalles posibles sobre el error, incluyendo el momento en que ocurrió, el método y nombre de la clase, etc. Capturando una excepción específica, no genérica. Cuando se vuelva a lanzar una excepción, utilice la instrucción throw sin especificar la excepción original. De esta manera, la llamada original conserva la pila de excepciones capturadas. Ejemplo: Código que representa una captura de excepciones: void ReadFromFile() { try { // funciones Read } catch(indexoutofrangeexception ex) { //Log Error //re-throw exception throw; } } 11. No escribir try-catch en todos sus métodos. Utilícelo sólo si hay una posibilidad de que una excepción específica se pueda producir y no se pueda evitar por cualquier otro medio. Por ejemplo, si desea insertar un registro en la base de datos. Algunos desarrolladores tratan de insertar un registro sin comprobar si este ya existe. Esto está estrictamente prohibido. Siempre debe comprobar si hay errores de forma explícita en lugar de esperar que se produzcan excepciones. Por otro lado, siempre debe utilizar 6

7 controladores de excepciones, si se comunica con sistemas externos, como de red, dispositivos hardware, etc. Estos sistemas están sujetos a fallos en cualquier momento y la comprobación de errores no suele ser fiable. En esos casos, debe tratar de recuperarse del error. 12. No escriba bloques try-catch muy grandes. Si es necesario, escribir por separado try-catch para cada tarea de realizar e incluya sólo la parte específica del código dentro del try-catch. Esto le ayudará a encontrar el código que genera la excepción y se puede dar mensaje de error específico al usuario. 13. Escriba sus propias clases excepción si se requiere en la aplicación: Heredar de Exception, o de otra clase base propia El nombre de la clase culminarlo con Exception Considerar proveer propiedades adicionales. 4.1 NOMENCLATURA Con el fin de establecer la forma en la cual se deben escribir los códigos fuente que se realicen para el DAPRE se establecen los siguientes lineamientos de nomenclatura: Se deberá utilizar Pascal Casing para los nombres de clases y para los nombre de los métodos El nombre del archivo debe coincidir con el nombre de la clase y debe respetar la notación Pascal Casing Se deberá utilizar Camel casing para nomenclar variables y parámetros de métodos Se deberá utilizar Pascal Case para nomenclar constantes Se deberá utilizar Pascal Case para nomenclar enumerados y su nombre debe estar expresado en forma singular (de igual forma están definidos en el.net framework). Cada miembro del enumerado deberá también ser nomenclado utilizando Pascal Case y deberá siempre tener un valor asignado explícitamente Utilizar el prefijo I con Pascal Casing para nomenclar Interfaces (Ejemplo: IUser) No se debe anteponer ningún prefijo que represente el tipo de datos de variables o constantes No utilice caracteres de subrayado (_) para nombres de variables locales. 7

8 4.1.9 Todas las variables de miembros deben estar precedidas por el carácter de subrayado (_) de modo que puedan diferenciarse de otras variables locales Utilizar prefijos como is o similares al nombrar variables de tipo bool. Ejemplo: Uso de los prefijos para nombramiento de variables private bool is Finished o bolfinished o bltfinished, etc Evite los nombres completo de tipo, en su lugar utilice la instrucción using Evite casting explícito. Use el operator as para defensivamente castear un tipo. 4.2 INDENTACIÓN, ESPACIADO Y AGRUPACIÓN DE CÓDIGO Con el fin de establecer el lineamiento de identación, espaciado y agrupación de código se establecen los siguientes lineamientos para la escritura del código fuente en las aplicaciones del DAPRE Utilice TAB de 4 posiciones para indentar código. No utilice espacios Los comentarios deben estar en el mismo nivel que el código, es decir que han de utilizar el mismo nivel de indentación Las llaves de apertura y cierre deben estar en el mismo nivel que el código fuera de éstas Utilice una línea en blanco para separar grupos lógicos de código Ejemplo: /// <summary> /// Carga los Datos para la consulta /// </summary> /// <param name="intdatoid">parametro de entrada con el valor de llave primaria</param> public void fnt_cargardatos(int intdatoid) { lblerror.text = string.empty; lblerror.cssclass = string.empty; Boolean bolresultado = false; int intconid = 0; //if (!String.IsNullOrEmpty(hdfConId.Value)) // intconid = int.parse(hdfconid.value); 8

9 int intleycomision = 0; //if (!string.isnullorempty((string)cboleycomisioncon.selecteditem.value)) // intleycomision = int.parse((string)cboleycomisioncon.selecteditem.value); Una única línea en blanco debe separar un método de otro, dentro de una clase Las llaves deben estar en una línea independiente y no en la misma línea que if, for, etc Utilizar un único espacio antes y después de cada operador, así como también entre términos utilizados durante la invocación de métodos Mantener las variables de miembro, propiedades y métodos en la parte superior del archivo, y miembros públicos en la parte inferior del mismo Utilizar # región para agrupar piezas de código relacionadas. Si se utiliza la agrupación adecuada mediante #region, una clase o página deberá lucir solamente con las regiones cuando todas las definiciones se contraigan. Mantener la variable miembro privadas, las propiedades y métodos privados en la parte superior del archivo y los miembros públicos en la parte inferior. 4.3 COMENTARIOS Comentarios correctos y significativos hacen al código más efectivo, sin embargo, se deben seguir los siguientes lineamientos: No comentar todas y cada una de las líneas de código ni cada variable declarada Utilizar // o /// para introducir comentarios. Evitar usar /* */ con comentarios de bloque Escribir comentarios donde sea requerido. Tener en cuenta que el buen código legible requerirá de pocos comentarios. Si todas las variables, métodos, constantes tienen nombres significativos, esto hará que el código sea fácilmente legible y no requiera de la introducción de comentarios en exceso No escribir comentarios en porciones en las que el código es fácilmente entendible y no requiere de conocimiento específico para su comprensión Si se debe utilizar lógica de negocio, se debe documentar correctamente con suficientes comentarios. 9

10 4.3.6 Si se inicializa una variable a un número especial distinto de 0, -1, String.Empty o Null, se deberá documentar la razón por la que se ha escogido dicho valor Corroborar ortografía, gramática y semántica de los comentarios, asegurándose de que la puntuación es utilizada correctamente. Agregar la documentación del encabezado de cada método (utilizando ///), especificando correctamente: El propósito del método Nombre, Tipo de datos y Contenido de cada parámetro recibido El propósito de la información retornada Esto es particularmente útil para generar documentación de forma automática, a partir de estos comentarios. Ejemplo: /// <summary> /// Carga los Datos para la consulta /// </summary> /// <param name="intdatoid">parametro de entrada con el valor de llave primaria</param> public void fnt_cargardatos(int intdatoid) { 4.4 TESTING UNITARIO Con el fin de establecer los parámetros requeridos para la creación de testing unitarios se definen los siguientes ítems para los diferentes escenarios de prueba que se apliquen en el DAPRE. Creación de test unitarios Cada test unitario deberá ser creado bajo la carpeta ProjectoName\Tests, y categorizado (en la forma de proyecto) en función del módulo al que corresponda. A su vez, dentro de cada proyecto de test, se deberá crear una carpeta con el mismo nombre del proyecto en el que se encuentra la clase para la cual se desea crear el Test. Cada archivo correspondiente a un test unitario, deberá ser nomenclado respetando el siguiente patrón: UnitTest + [Nombre Clase que se testea] Cada nombre de método cumplirá con la forma Test_ + [Nombre Método] + [Descripción de Entrada] 10

11 Ejemplos: Los test unitarios correspondientes al módulo de Customers, deberán ser colocados bajo la carpeta ProjectoName\Tests en el proyecto Customers. Si se desea verificar el método ValidateCustomer de una clase de nombre CustomerServices, correspondiente al módulo Customers se seguirán los siguientes pasos: Se creará la clase UnitTestCustomerServices y se ubicará en Projecto\Tests\Customers. Dentro de la clase antedicha, se creará el método de Test_ValidateCustomer_InvalidNumbers. Se agregará código para verificar que la validación de clientes opera de acuerdo a lo esperado cuando recibe ingresos no válidos. Alcance de la validación Cada método de validación que sea creado debe contemplar los casos que se tracen como posibles escenarios de ejecución válidos, incluyendo casos de borde. 4.5 ORGANIZACIÓN DE TESTS Para cada módulo de la solución se deberá crear una Test List (Menú Test, Create Test List) que incluya todos los test asociados al módulo. Esto permitirá que los mismos sean administrados de forma conjunta. Prácticas recomendadas Evitar crear dependencias entre tests que impliquen que deban ser ejecutados en un orden particular. Cada test unitario debe ser independiente Asegurarse de que los tests cubren todas las operaciones definidas en cada servicio Crear una clase de test para cada una de las clases que se desean verificar. Esto simplificará la organización de los tests y facilitará la tarea de seleccionar la ubicación de cada uno de ellos Evitar crear tests que involucren información específica del equipo, como por ejemplo versiones de software, tipo de arquitectura de procesador, rutas de acceso. 11

12 4.5.5 Ejecutar absolutamente todos los test desarrollados, cuando se realojen cambios, antes de hacer check-in y previo al empaquetado de una nueva versión. 4.6 PLATAFORMA DESARROLLO La plataforma de desarrollo establecida en el DAPRE requiere de las siguientes herramientas tecnológicas, con las cuales se cuenta actualmente: IDE de desarrollo Visual Studio Framework 4.0 con Lenguaje. Sistema Operativo Windows Server 2008 R2 Standard. Motor de Base de datos SQL Server 2008 R2 Enterprise. Componente de Controles DevExpress Version MARCO LEGAL Decreto 1360 de Por el cual se reglamenta la inscripción del soporte lógico (software) en el Registro Nacional del Derecho de Autor, artículos del REQUISITOS TÉCNICOS Norma Técnica ISO/IEC 23270:2006 Tecnología de Información- Programando en el lenguaje, Language Specification ECMA INTERNATIONAL Standard ECMA-334 4th edición Junio

13 7 DOCUMENTOS ASOCIADOS C-TI-11 Caracterización proceso tecnologías de información y comunicaciones 8 RESPONSABLE DEL DOCUMENTO JEFE DE AREA DE INFORMACION Y SISTEMAS 13