Teoría sobre Optimización e documentación

Obxectivos

Máis ala de programar código... qué debe coñecer e facer un bo programador?

Debe, entre outros conceptos:

• saber cómo refactorizar o código utilizando patróns de deseño
• usar sistemas de control de versións
• realizar unha documentación útil e eficaz.

Refactorización

Concepto e limitacións

Refactorizar é cambiar un código para que sexa máis lexible e fácil de manter nun futuro pero sen cambiar a súa funcionalidade.

Os cambios nunca modificarán o aspecto externo dunha clase ou programa, que se comportará de xeito idéntico.

As vantaxes da refactorización son:

• Facilitará que o programador atope erros dunha forma máis rápida e sinxela
• Permitirá programar máis rápido
• O código será mais lexible e máis doado de interpretar
• Os deseños serán máis robustos
• Os programas terán máis calidade
• Evitarase a duplicación da lóxica dos programas

DRY (don't repeat yourself) é o oposto a WET (write everything twice, we enjoy typing ou waste everybody's time).

Patróns máis habituales

Extract method ou reducción lóxica

Código antes de refactorizar:

 void imprimirConta(String nome, double cantidade)
   imprimeLogo()
   System.out.println("nome+"nome);
   System.out.println("cantidade+"cantidade);
 }

Código despois de refactorizar:

 void imprimirConta(String nome, double cantidade){
   imprimeLogo()
   imprimirDetalles(nome,cantidade)
 }
 void imprimirDetalles(String nome, double cantidade){
   System.out.println("nome+"nome);
   System.out.println("cantidade+"cantidade);
 }

Este tipo de refactorización e unha das máis sinxelas e típicas; hay que crear métodos que fagan o que din.

Os métodos cortos teñen coma vantaxes:

• Realizan tarefas concretas (é son por tanto máis fáciles de reutilizar)
• Permiten ir creando outros métodos cun nivel de complexidade maior.

Métodos inline ou código embebido

Código antes de refactorizar:

 int rondaGratis(){
   return (masde5cañas())?2:1;
 }
 boolean masde5cañas(){
   return numerodecañas > 5;
 }

Código despois de refactorizar:

 int rondaGratis(){ 
 return (numerodecañas > 5)?2:1; 
}

Ocultar a lóxica do programa factorizando o código é mala idea cando se pretende escribir métodos e código que amosen a intención do código. Observase no exemplo anterior que o código queda máis simple e fácil de entender eliminando a función xa que se reduce a súa complexidade e queda un código máis lexible.

En Java hai métodos que sobrecargan métodos de clases base, que fan inadecuadas estas formas de programar.

Outro exemplo de código embebido que debemos evitar é :

double preciobase = pedido.preciobase(); 
return (preciobase > 100);

Este código sería máis aconsellable:

return (pedido.preciobase()>100);

Utilíza neste caso unha variable temporal só para realizar aa comparación; uhna forma máis elegante e que evita problemas sería empregar a comparación directa cando realizamos o return.

Evita utilizar variables temporais para almacenar resultados intermedios das operacións.

Por exemplo, neste código:

 double preciobase = cantidad * preciounitario; 
 if (preciobase > 1000) return preciobase * 0.90; else return preciobase * 0.95;
    return preciobase * 0.90;
 else
    return preciobase * 0.95;
 }

É mellor deixar este código:

 if (precioBase() > 1000) 
    return preciobase 0.90; 
 else 
    return preciobase 0.95; 
 ...
 double precioBase(){ 
 return cantidad preciounitario; 
 } 

No exemplo anterior desea realizarse un desconto ó cliente:

Se a conta supera unha determinada cantidade, pagará un 90% (desconto dun 10%), 
En caso contrario, o desconto será soamente dun 5%.

Como vimos anteriormente, utilízase unha variable temporal para calcular o precio base dunha conta. En vez de utilizar una variable temporal é mellor utilizar un novo método cun nome suficientemente explicativo para determinar o precio base; este método poderá ser empregado por outros métodos da clase incrementando a súa utilidade.

Imaxina que queres utilizar unha variable sen ter que crear un método para factorizarla; neste caso recomendase empregar variables final xq que permite asignarlle un valor e preven dunha doble instanciación porque el compilador vai mostrar o erro.

Por ejemplo, o seguiente código mostrará un error:

final double preciobase; 
preciobase = cantidad*precio; 
preciobase = cantidad*precio*0.9;

E así, o método pode ser redefinido do seguinte xeito:

final int preciobase = cantidad precio; 
final double descuento; 
if (preciobase > 1000) descuento = 0.9; 
else descuento = 0.95; 
return preciobase descuento;

Uso ee analizadores de código

• Uso de analizadores de código

La documentación

Todo el proceso de desarrollo de software debe quedar perfectamente documentado, para pasar así de una fase a otra de forma clara y definida. Además, es importante también para poder acometer futuras revisiones del proyecto.

Las 7 C de la escritura técnica

Toda la documentación debería seguir estos principios:

• Clara: El objetivo es que la documentación sea sencilla de leer, de seguir y de comprender
• Concreta: Usar frases y palabras precisas con un único significado
• Concisa: Incluir toda la información que el usuario debe de conocer para ejecutar una acción concreta; no todo lo que idealmente puede saber.
• Cohesiva: Organizar el contenido de modo que siga un flujo lógico de información
• Consistente: Usar la misma terminología y estilo a lo largo de todo el documento
• Completa: Incluir toda la información necesaria para que el usuario ejecute de manera eficar procedimientos y acciones
• Coherente: Organizar el contenido de un modo que tenga sentdido y sea sencillo de entender

Errores comunes

Es interesante conocer cuáles son los errores más frecuentes para evitarlos. La documentación puede:

• Ser díficil de encontrar o estar en un lugar incorrecto
• No tener o tener demasiadas capturas de pantalla
• Tener demasiada narrativa o sólo videos
• Contener instrucciones que no están separadas por pasos
• Tener tíulos largos o poco descriptivos
• Estar desactualizada

Proceso de mejora de la usabilidad de la documentación

El mejor modo de saber si nuestra documentación es útil es midiendo su impacto. Para ello es necsario KPIs para medir la UX

Algunos posibles indicadores serían:

KPIs

Satisfacción de los usuarios	Usabilidad y ayuda	Calidad de la documentación
Net Promoter Score (NPS): tener más promotores que detractores	Encuestas e iconos de sentimientos	Feedback en soporte
Visitas al sitio: recurrentes vs nuevos	Keywords y técnicos más buscados	Net Promoter Score (NPS)
Inbound links: enlaces desde sitios externos	CTR, tasas recote, salidas	Casos de soporte resueltos

Un proceso de mejora que tenga en cuenta esos indicadores podría seguir estas fases:

1. Revisa los casos de soporte
2. Crea nueva documentación, mejora la existente y borra la desactualizada
3. Realiza test A/B
4. Mide resultados con los indicadoes

Tipos de guías

Se distinguen tres grandes documentos en el desarrollo de software:

Guía técnica

Información que contiene:

• El diseño de la aplicación.
• La codificación de los programas.
• Las pruebas realizadas.

Está dirigido a:

• Personal técnico en informática (analistas y programadores)

El objetivo es:

• Facilitar un correcto desarrollo, realizar correcciones en los programas y permitir un mantenimiento futuro.

Guía de uso

Información que contiene:

• Descripción de la funcionalidad de la aplicación.
• Forma de comenzar a ejecutar la aplicación.
• Ejemplos de uso del programa.
• Requerimientos software de la aplicación.
• Soluciones de los posibles problemas que se pueden presentar.

Está dirigido a:

• Usuarios que van a utilizar la aplicación (clientes).

El objetivo es:

• Dar a los usuarios finales toda la información necesaria para utilizar la aplicación.

Guía de instalación

Información que contiene:

• Toda la información necesaria sobre puesta en marcha, explotación y seguridad del sistema.

Está dirigido a:

• Personal informático responsable de la instalación, en colaboración con los usuarios que van a usar la aplicación (clientes).

El objetivo es :

• Dar toda la información necesaria para garantizar que la implantación de la aplicación se realice de forma segura, confiable y precisa.

Resumo

• Refactorizar é modificar un programa, clase, ou método para que sexa
  • máis eficiente
  • máis mantenible
  • de máis calidade
  • pero sen modificar o aspecto externo!
• Os patróns de refactorización máis comúns son:

• • Extract method.
  • Métodos inline.
  • Variables autoexplicativas.
  • Uso de variables temporales.
  • Modificación de algoritmos.
  • Mover métodos entre clases.
  • Mover variables miembro entre clases.
  • Autoencapsulación de campos.
  • Extracción de clases.
  • Clases delegadas.
  • Foreign methods.
  • Reemplazar valores con objetos.
  • Encapsulación de arrays.
  • Reemplazar tipos de objetos con subclases.

• Un sistema de control de versions serve para levar un control dos distintos cambios que pode sufrir un producto software durante o seu desenvolvemento ou vida útil.
• Poden ser sistemas:
  • sistemas centralizados.
  • sistemas distribuidos.
• Poden existir os seguintes tipos de colaboración:
  • en exclusiva
  • de xeito colaborativo: fluxo de traballo centralizado ou workflow centralizado, con xestor de integración, con dictador e tenentes.
• Cómo escribir documentación de calidade:
  • facer esquemas
  • clasificar
  • síntesis
  • usar estándares e ferramentas de documentación.
  • claridade na expresión.
  • Ter en conta o nivel do usuario
• La documentación de un software debe cubrir tanto el aspecto técnico como el aspecto funcional. El aspecto técnico está más orientado a los desarrolladores y el funcional a los usuarios.
• Durante o ciclo de vida dun proxecto, aa documentación:
  • é unha tarefa que se inicia con él e termina tamén con él
  • aínda que realmente, é un proceso que nunca termina

Referencias

• NobleProg PHP Optimización