instructivo de buenas prácticas de desarrollo de software

INSTRUCTIVO DE
BUENAS PRÁCTICAS DE DESARROLLO DE SOFTWARE
Bogotá D.C. Agosto 2016
INSTRUCTIVO DE
BUENAS PRÁCTICAS DE
DESARROLLO DE SOFTWARE
Proceso asociado: Tecnología de Información y Comunicaciones
Código: I - TI - 01
Versión 01
TABLA DE CONTENIDO
1.
2.
3.
INTRODUCCIÓN ----------------------------------------------------------------------------------- 3
ALCANCE -------------------------------------------------------------------------------------------- 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 --------------------------4
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
2
INSTRUCTIVO DE
BUENAS PRÁCTICAS DE
DESARROLLO DE SOFTWARE
Proceso asociado: Tecnología de Información y Comunicaciones
1.
Código: I - TI - 01
Versión 01
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 – LTI-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
var
var
var
var
bolEsEstadoActivo = false;
dblValorPromedioComision = 0;
intCantidadAprobaciones = 0;
datInicioContrato = new DateTime(1900,1,1);
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
3
INSTRUCTIVO DE
BUENAS PRÁCTICAS DE
DESARROLLO DE SOFTWARE
Proceso asociado: Tecnología de Información y Comunicaciones
Código: I - TI - 01
Versión 01
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
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(),
4
INSTRUCTIVO DE
BUENAS PRÁCTICAS DE
DESARROLLO DE SOFTWARE
Proceso asociado: Tecnología de Información y Comunicaciones
//
//
//
//
//
Código: I - TI - 01
Versión 01
ConfigurationManager.AppSettings["wsTarvos.app"].ToString(),
ConfigurationManager.AppSettings["wsTarvos.template"].ToString(),
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:
string fntLeerDesdeArchivo ( string strNombreArchivo )
{
try
{
5
INSTRUCTIVO DE
BUENAS PRÁCTICAS DE
DESARROLLO DE SOFTWARE
Proceso asociado: Tecnología de Información y Comunicaciones
Código: I - TI - 01
Versión 01
// 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.
 Mala práctica:
public string fntConsultarProcesarRegistrarNotificarStr(string strSP, bool bitTrans) {
…
}
 Buena práctica:
6
INSTRUCTIVO DE
BUENAS PRÁCTICAS DE
DESARROLLO DE SOFTWARE
Proceso asociado: Tecnología de Información y Comunicaciones
Código: I - TI - 01
Versión 01
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)
 Buena práctica:
public bool fntConsultarUsuarioBol(string strNombre, bool bitTrans)
7
INSTRUCTIVO DE
BUENAS PRÁCTICAS DE
DESARROLLO DE SOFTWARE
Proceso asociado: Tecnología de Información y Comunicaciones
Código: I - TI - 01
Versión 01
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);
// Aqui se utiliza la excepción
// var estoEsAlgoQueNoUtilizo;
fntRectifico(ex);
// Aqui se utiliza la excepción
// fntEstaFuncionYaNoLaUso();
8
INSTRUCTIVO DE
BUENAS PRÁCTICAS DE
DESARROLLO DE SOFTWARE
Proceso asociado: Tecnología de Información y Comunicaciones
Código: I - TI - 01
Versión 01
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ía y Sistemas de Información
9