INSTRUCTIVO DE BUENAS PRÁCTICAS DE DESARROLLO DE SOFTWARE · Administrativo de la Presidencia de...

INSTRUCTIVO DE BUENAS PRÁCTICAS DE DESARROLLO DE SOFTWARE

BOGOTÁ D.C. SEPTIEMBRE 2019


Proceso asociado

Código

Versión

I-TI-01

02

2

Tecnología de Información y Comunicaciones

CONTENIDO

1. INTRODUCCIÓN --------------------------------------------------------------------------------------------- 3

2. ALCANCE ------------------------------------------------------------------------------------------------------ 3

3. PRÁCTICAS RECOMENDADAS --------------------------------------------------------------------------- 3

3.1. Utilizar nombres descriptivos --------------------------------------------------------------------------- 3

3.2. Separar la lógica de la Presentación ------------------------------------------------------------------- 3

3.3. Escribir comentarios de funciones, definiciones y lógica compleja --------------------------- 3

3.4. Evitar comentarios innecesarios ----------------------------------------------------------------------- 4

3.5. Evitar anidaciones profundas de instrucciones ----------------------------------------------------- 5

3.6. Retornar las excepciones capturadas ----------------------------------------------------------------- 5

3.7. Evitar usar métodos con muchos parámetros ------------------------------------------------------ 6

3.8. Programar métodos que solo hagan una tarea ----------------------------------------------------- 6

3.9. No hacer comparaciones explícitas -------------------------------------------------------------------- 7

3.10. No utilizar parámetros out o ref ------------------------------------------------------------------------ 7

3.11. Utilizar preferiblemente tipos nativos ---------------------------------------------------------------- 8

3.12. Nombre los métodos en la forma fntVerboObjeto ------------------------------------------------ 8

3.13. Evite comentarios inline ---------------------------------------------------------------------------------- 8

4. RESPONSABLE DEL DOCUMENTO ---------------------------------------------------------------------- 9


Proceso asociado

Código

Versión

I-TI-01

02

3


1. INTRODUCCIÓN Este documento brinda orientaciones para aplicar de la mejor manera, los estándares y lineamientos de codificación establecidos por el Área de Tecnología y Sistemas de Información del Departamento Administrativo de la Presidencia de la República, teniendo en cuenta las mejores prácticas para el desarrollo de software.

2. ALCANCE Aplican para el desarrollo de todos los proyectos de software que se estén ejecutando en la entidad, acorde con el documento Lineamiento de Desarrollo de Software – L-TI-14.

3. PRÁCTICAS RECOMENDADAS

Utilizar nombres descriptivos

Los nombres deben hacer alusión a su significado o razón de ser y NO a su tipo. Mala práctica:

var1, var2, miVariable, miDato, label1, consularDato(), int1, string2 …. Buena práctica:

var bolEsEstadoActivo = false; var dblValorPromedioComision = 0; var intCantidadAprobaciones = 0; var datInicioContrato = new DateTime(1900,1,1); var dsSolicitud = fntObtenerSolicitudPorID_ds(int intIdSolicitud);

Separar la lógica de la Presentación Mantener al mínimo la lógica de negocio, cálculos complejos, operaciones, lectura de archivos y sobre todo las consultas a la base de datos dentro de la capa de presentación, formularios web, controles y cualquier elemento que se encuentre esta capa. En los formularios únicamente se debe capturar la información proporcionada por los usuarios y responder a los eventos y acciones que este realice.

Escribir comentarios de funciones, definiciones y lógica compleja


Proceso asociado

Código

Versión

I-TI-01

02

4


Describir lo que se está haciendo ayuda a recordar las funcionalidades que se están programando y a validar que el resultado esperado está acorde a su definición. Mala práctica: public string GetContentFillerText(){ … Buena práctica:

/// <summary> /// Valida que el usuario logeado, este dentro de un rol específico /// </summary> /// <param name="intRol">rol a validar</param> /// <returns>esta o nó dentro del rol</returns> protected bool ResuelveRoles(int intRol) /// Si hay varios itinerarios, valida que no se repitan los ultimos if (intContieneFuncionarios) { if (esDiferenteOrigen){ strError = "El origen no puede ser igual al origen del trayecto anterior"; return false; } if (esDiferenteDestino)) { strError = "El destino no puede ser igual al destino del trayecto anterior"; return false; } }

Evitar comentarios innecesarios

Prevenir que en el código aparezcan comentarios excesivos, que describan lo obvio o líneas de código comentadas: Mala práctica:

/// si el país es igual a co if (bolPais == "co”) { try { //notice notif = new notice(); //string strNotificacion = notif.notificaUsuario(AppSettings["wsTarvos.usr"]); // ConfigurationManager.AppSettings["wsTarvos.pwd"].ToString(), // ConfigurationManager.AppSettings["wsTarvos.app"].ToString(), // ConfigurationManager.AppSettings["wsTarvos.template"].ToString(),


Proceso asociado

Código

Versión

I-TI-01

02

5


// ConfigurationManager.AppSettings["wsTarvos.ref"].ToString(), // sbMensaje.ToString(), // strDestinatarios); string strDeBck = ConfigurationManager.AppSettings["emailbck.de"].ToString(); …

Evitar anidaciones profundas de instrucciones Mantener al mínimo el número de niveles en las instrucciones anidadas. Mala práctica:

if (inttipoViaje == (byte)tipoViaje.nacional) { // Nacional if (!string.IsNullOrEmpty(ddlDepartamento.SelectedValue)) { if (!string.IsNullOrEmpty(ddlvirEstado.SelectedValue)) { if (!string.IsNullOrEmpty(txtviafechallegada.Text)) { …

Retornar las excepciones capturadas En general, capturar excepciones oculta errores y nos dificulta la depuración de las aplicaciones. Solo se deben capturar para registrar el error y luego retornar la misma excepción si es posible con un mensaje descriptivo. Mala práctica:

string fntLeerDesdeArchivo ( string strNombreArchivo ) { try { // leer el archivo } catch (Exception ex) { // Aqui se esta ocultando la excepción // En este caso nadie sabrá que ocurrio una excepción. return "";

Buena práctica:


Proceso asociado

Código

Versión

I-TI-01

02

6


string fntLeerDesdeArchivo ( string strNombreArchivo ) { try { // leer el archivo } catch (Exception ex) { // Aqui se utiliza la excepción fntRegistrarLog(ex); // Se devuelve la excepción return new Exception("Ocurrió un error al abrir el archivo: ", ex);

Evitar usar métodos con muchos parámetros

Si por alguna razón es necesario utilizar métodos que contengan muchas entradas de información, es mejor declarar una clase con contenga las propiedades que se están ingresando. Máximo 3 parámetros por función. Mala práctica:

public void Checkout(string shippingName, string shippingCity, string shippingSate, string shippingZip, string billingName, string billingCity, string billingSate, string billingZip) { ... }

Buena práctica:

public void fntCheckout(ShippingAddress shippingAddress,BillingAddress billingAddress) {

...

}

Programar métodos que solo hagan una tarea

Hacer más no siempre es bueno, si un método tiene más de 7 líneas ó no se alcanza a ver en la pantalla, puede ser que tenga muchas responsabilidades, es una buena práctica romperlo en varios métodos mas simples y con nombres que se expliquen solos.


Proceso asociado

Código

Versión

I-TI-01

02

7


Mala práctica:

public string fntConsultarProcesarRegistrarNotificarStr(string strSP, bool bitTrans) { … } Buena práctica:

public int fntSumarDosNumerosInt(int intNumero1, int intNumero2 ) { … }

No hacer comparaciones explícitas Generalmente es mala práctica comparar expresiones boleanas con true o false, es mejor asignar la condición a una variable y utlizar la variable en las comparaciones, nombre las variables de forma afirmativa Mala práctica:

if (!condicion1 = false) … while (noContieneRegistros ¡= true) … if (!((condicion3 == true) == false) == true) ... Buena práctica:

var bolEsUsuarioActivo = fntConsultarUsuarioDirectorioUsr(strNombreUsuario) ¡= null if (bolEsUsuarioActivo) … while (bolExistenRegistros)

No utilizar parámetros out o ref Si es posible, retornar objetos compuestos, parámetros de referencia o de salida, solamente hacen el código menos legible y son propensos a introducir bugs en el código. Mala práctica:

public Boolean fntConsultarBol(ref string strDataSet, string formarfecha)


Proceso asociado

Código

Versión

I-TI-01

02

8


Buena práctica:

public bool fntConsultarUsuarioBol(string strNombre, bool bitTrans)

Utilizar preferiblemente tipos nativos A menos que sea necesario, solamente utilizar los tipos nativos: int, bool, byte, string y evitar los Alias como String, Int32, Boolean …

Nombre los métodos en la forma fntVerboObjeto Un buen nombre da una explicación del qué se está haciendo y en lo posible, evite la palabra Y (And) o (Or) si esto ocurre puede ser que se está haciendo algo más de los que se debe. Buena práctica:

fntConsultarUsuariosLst(), fntGuardarSolicitudBol(), fntValidarRol(), fntMostrarDialogo()

Evite comentarios inline

En lo posible, los comentarios deben ir sobre: Métodos, variables públicas o privadas, propiedades. Si hay un comentario inline, evalúe la posibilidad de extraer un método explícito. Los comentarios debes estar enfocados a explicar el porqué y el qué y no el cómo. Mala práctica:

public void fntHagoMuchasCosasComplejas(string strNombre, string strDirectorio) { // Aqui se utiliza la excepción fntHagoMuchasCosas(ex); // Aqui se utiliza la excepción fntCalculoOtrasCosas (ex); // Aqui se utiliza la excepción // var estoEsAlgoQueNoUtilizo; fntRectifico(ex); // Aqui se utiliza la excepción // fntEstaFuncionYaNoLaUso(); fntRegistrarLog(ex); // no devuelvo nada // Aqui se utiliza la excepción fntHagoMuchasCosas(ex); // Aqui se utiliza la excepción fntCalculoOtrasCosas (ex);


Proceso asociado

Código

Versión

I-TI-01

02

9


// Aqui se utiliza la excepción // var estoEsAlgoQueNoUtilizo; fntRectifico(ex); // Aqui se utiliza la excepción // fntEstaFuncionYaNoLaUso(); fntRegistrarLog(ex); // no devuelvo nada Return; }

Buena práctica:

public ClaseCompleja fntHagoAlgoAutoexplicatorio(ClaseCompleja objClaseCompleja) {

objClaseCompleja.Estado = "Ocurrió un error al abrir el archivo: ";

}

public void fntHagoAlgoMuyComplejo(ClaseCompleja objClaseCompleja, OtraClase objOtro) {

fntHagoAlgoAutoexplicatorio(objClaseCompleja);

objOtro.Activo = false;

objOtro.fntProcesar(objClaseCompleja);

}

4. RESPONSABLE DEL DOCUMENTO Jefe Área de Tecnologías y Sistemas de Información.

INSTRUCTIVO DE BUENAS PRÁCTICAS DE DESARROLLO DE SOFTWARE · Administrativo de la Presidencia de...

Documents

Transcript of INSTRUCTIVO DE BUENAS PRÁCTICAS DE DESARROLLO DE SOFTWARE · Administrativo de la Presidencia de...