Políticas Generales de Desarrollo

Introducción

Próposito

Establecer las políticas que permitan estandarizar el desarrollo de software, logrando la creación de sistemas que sean fáciles de comprender y de mantener, además de permitir tener una mayor cantidad de código reutilizable que sea menos propenso a los errores.

Alcance

Después de la aprobación de este documento, las políticas aquí establecidas serán utilizadas para llevar a cabo las revisiones de código (Peer Review) que correspondan.

Audiencia

Este documento esta dirigido a Programadores, Líderes Técnicos, Coordinadores de Desarrollo y cualquier persona involucrada directamente con el desarrollo de software.

Políticas Generales de Desarrollo

Archivos

• El nombre de cada archivo debe coincidir con el nombre de la clase o componente que contiene.
• Cualquier clase o componente debe ser fácilmente identificado, a través de su nombre, es decir, el nombre de cada archivo de código debe ser descriptivo.
• Se debe definir una sola responsabilidad por archivo.
• La organización de los archivos deberá respetar el patrón establecido por el lenguaje de programación que se esté utilizando.
• Cada archivo debe abarcar una responsabilidad específica (estilos, scripts, código, etc.), evitar que un archivo contenga más de una responsabilidad, a menos de que así lo indique el lenguaje de programación o framework utilizado.

Clases

• Cada clase debe tener responsabilidad sobre una sola parte de toda la funcionalidad proporcionada por el sistema y esta funcionalidad debe estar encapsulada en su totalidad por una clase.
• Mantener clases que definen Entidades (Base de Datos, por ejemplo), separadas de aquellas que implementan únicamente funcionalidades. Las clases que definen entidades no implementan métodos.
• Las propiedades de una clase deberán ser colocadas antes que sus métodos.
• El encabezado de la clase deberá estar conformado por un bloque de comentarios que defina el objetivo de la clase y cualquier conjunto de reglas de negocio que sea necesario conocer para el correcto entendimiento de los flujos desarrollados.
• Una vez definida la responsabilidad de cada clase, se debe evitar la adición de cualquier código que distorsione dicha responsabilidad; en su lugar, se deberá hacer uso del concepto de Herencia para extender su funcionalidad.
• Una clase debe evitar cualquier dependencia de código que se pueda producir, a través del uso de Interfaces y de patrones como Inyección de Dependencias.

Métodos

• Cada método definido deberá contener su correspondiente porción de documentación (definida por cada uno de los lenguajes), especificando el objetivo del método, además del tipo y definición de cada uno de sus parámetros.
• Cada método deberá cumplir con una función específica. Evitar que un mismo método realice más de una actividad específica.
• Evitar que un método genere o integre dependencias.
• Cualquier método que funcione como end point debe retornar un código de respuesta que corresponda con los establecidos para el protocolo HTTP.

Nombramiento

• Debe existir consistencia en todo el código cuando se nombran variables, clases, métodos y cualquier otro componente que conforme la totalidad del sistema. Esta consistencia abarca también el idioma para la declaración de variables y para la colocación de comentarios de código.
• Se debe respetar el patrón de nombramiento definido para cada uno de los lenguajes utilizados.
• Utilizar la nomenclatura establecida por el lenguaje de programación, para la definición de métodos, variables y cualquier otro elemento.

Variables

• Evitar la declaración de variables que no sean utilizadas
• Utilizar estructuras globales que permitan mantener un catálogo específico de constantes que puedan ser consideradas por cualquier clase o componente

Comentarios

• Las partes importantes de código deben estar comentadas (reglas de negocio, consideraciones específicas para un cierto flujo, etc.)
• Evitar líneas de código comentado

Excepciones

• Cualquier flujo del sistema debe ser controlado a través de excepciones, sin suponer que ciertas circunstancias nunca ocurrirán
• No deben existir bloques catch que no lleven a cabo una acción específica para ejecutar operaciones específicas que permitan tomar decisiones ante cualquier problema
• Mantener un estándar de registro de excepciones
  • Visor de eventos para sistemas legados
  • Archivos de texto para nuevos desarrollos
• Mantener un mismo estándar de escritura de registros log, considerando lo siguiente
  • Fecha y Hora
  • Código de error
  • Clase en la cual se produce la excepción
  • Método en la cual se produce la excepción
  • Descripción (captura de la excepción)
• Registrar únicamente excepciones y cualquier información que sea realmente útil para localizar errores en producción
• Controlar excepciones específicas para cada uno de los componentes involucrados (por ejemplo, SQL), además de excepciones globales (por ejemplo, el objeto Exception). Las capturas de excepciones específicas deben colocarse antes que la captura de la excepción general.

Referencias

A continuación, se enlistan las referencias oficiales que serán consideradas como línea base para el correcto cumplimiento de los puntos mencionados anteriormente.

Microsoft

• Naming Guidelines
• Type Design Guidelines
• Member Design Guidelines
• Designing for Extensibility
• Design Guidelines for Exceptions
• Usage guidelines
• Common Design Patterns

Angular

• Angular coding style guide

JavaScript

• Google JavaScript Style Guide
• JavaScript Guidelines

React Native

• Standards and Guidelines

Java

• Google Java Style Guide
• Java Code Conventions

Archivo Fuente: http://192.168.9.60:8080/scm/svn/Telstock-Documentation/Documentacion/Desarrollo/TSK%20-%20Pol%C3%ADticas%20Generales%20de%20Desarrollo.docx