PHP Senior: calidad

Mostrando las entradas con la etiqueta calidad. Mostrar todas las entradas

[SVN] Agregar notificación por email en caso de cambios en el repositorio

Esto es muy productivo en cualquier equipo de trabajo, recibir notificación por email de cada vez que ocurre un cambio en un repositorio de un proyecto donde estés trabajando, esto permite tener a todo el equipo notificado y coordinado con los cambios, y en caso de problemas poder detectarlo rápidamente (se tocó un archivo que no correspondía, un error, cambio no planeado, etc). También permite aumentar el contro de calidad si esto es revisado por el teamleader (o un responsable de QA) que revise si se cumplen los criterios de calidad prefijados.

Les dejo la configuración que hay que hacer en el hosting dreamhost.com, pero que también pueden aplicar en vuestros servidores:

En el directorio del proyecto SVN tienen que buscar el subdirectorio hooks, y copiar el archivo de ejemplo post-commit.tmpl como post-commit (donde agregaremos todas las acciones que queremos que ocurran una vez que existan un commit):

#!/bin/sh

REPOS="$1"
REV="$2"

/usr/share/subversion/hook-scripts/commit-email.pl --from info@surforce.com "$REPOS" "$REV" desa1@gmail.com desa2@gmail.com desa3@gmail.com

Y listo, ahora luego de que cualquier desarrollador haga un commit, nos llegará a todos un email con un diff con los cambios realizados, por ejemplo:

Author: alejandro145
Date: 2009-12-04 14:49:01 -0800 (Fri, 04 Dec 2009)
New Revision: 16

Modified:
public/js/jquery/ui/themes/ui-
lightness/ui.datepicker.css
Log:
Cambia el tamaño del widget para elegir fechas

Modified: public/js/jquery/ui/themes/ui-lightness/ui.datepicker.css
===================================================================
--- public/js/jquery/ui/themes/ui-lightness/ui.datepicker.css 2009-12-04 21:48:09 UTC (rev 15)
+++ public/js/jquery/ui/themes/ui-lightness/ui.datepicker.css 2009-12-04 22:49:01 UTC (rev 16)
@@ -1,5 +1,7 @@
/* Datepicker
----------------------------------*/
+.ui-widget.ui-datepicker { font-size:.8em }
+
.ui-datepicker { width: 17em; padding: .2em .2em 0; }

Las líneas agregadas aparecen a la izquierda con un "+" o un "-" si estas son eliminadas.

Que les sirva de referencia para su trabajo en equipo ;-)

PD: por las dudas, ya que es un error que he cometido seguido, el scripts tiene que tener permisos de ejecución (confunde muchas veces que el ejemplo .tmpl no tenga permisos de ejecución, y uno viene y lo copia directamente y piensa que es solo cambiar el contenido), ya que es SVN lo tiene que ejecutar.

Comentar código de forma "invisible"

Este tema tiene un origen histórico, trataré de empezar desde el principio ;-)

Cuando hace años empezamos en el mundo estático del "html" (cuando el 95% de los sitios solo eran puro html sin dinamismo, sin un lenguaje de scripting), lo que aprendimos fue a "programar html" haciendo muchas tablas (no usábamos los div's como ahora) y para seguir la "cascada" de código le agregábamos comentarios usando el tradicional 

Por ejemplo:

Muy "cómodo" para hacer debug "manual" usando de apoyo los comentarios porque evidentemente era un "humano" el que debía controlar todo esto y se podía perder entre tanto código en cascada ;-)

Para los "técnicos" esto siempre fue desprolijo, ya que para nuestros futuros clientes o hasta curiosos, estábamos revelando detalles internos de nuestra aplicación / diseño. Está de más decir que no es para nada recomendable hacer comentarios técnicos importantes en ellos ya que es "código público" que cualquiera puede leer, y tampoco comentar código que no se va a usar, ya que es extremadamente desprolijo (si no lo quieres perder, respalda, o versiona).

Nota: no será la primera y última vez que veo en los comentarios de un código html insultos del propio desarrollador, que la verdad queda muy feo ;-)

Primer sugerencia, el código de producción debe estar "limpio", y si conoces algún sistema que pueda contener los comentarios en tu código de desarrollo e impida que quede en producción, úsalo.

Algunos ejemplos.

Usando el propio lenguaje de scripting: PHP

Cuando la tecnología evolucionó y empezamos a contar con lenguajes de scripting como PHP, la primera práctica que empezamos a adoptar fue el de embeber el código "dinámico" dentro de nuestro código html, pero dejamos todas las demás prácticas intactas, por lo que los comentarios seguían estando públicos en el html.

Con el tiempo, dejamos de "embeber" y ya no era tan evidente la manipulación del código html, empezamos a hacer invocaciones a funciones de tipo:

     generarCabezalHtml();
generarContenido('Hola Mundo');
generarPie();

Por lo que ya no es el "humano" que debe seguir tan literalmente el código, ver si cierra o no, porque podemos validarlo a través de herramientas, y luego tratar de seguirlo a través del código PHP (aquí también ayudan mucho los IDEs en la pre-validación del código y evitar errores).

Una opción posible es mover todos los comentarios html al código php y estos quedan "privados" dentro del sistema.

Si esto no fuera suficiente, aún se podría generar algo como una configuración que diga "habilitarComentariosHtml" y que genere html con comentarios embebidos, y una vez en producción, eliminar esta opción (pero estaríamos generando mucho código poco productivo para el sistema).

Sigamos un siguiente nivel en la escala evolutiva ;-)

Usando sistemas de plantillas: Smarty

Con los años esto no nos quedó muy cómodo y preferimos optar por un sistema de "plantillas" (templates), y limpiar nuestro código PHP. Smarty fue una de las mejores opciones por años, lo cual te ofrecía además un código simil PHP del lado del template, pero podíamos volver a caer en la misma práctica, hacer comentarios html públicos.

Repitiendo lo que hablamos en el punto anterior, podíamos adoptar el mecanismo de comentarios de Smarty, lo cual genera el mismo efecto que hacerlo desde PHP. Se hacía con {* comentarios *}

{* display dropdown lists *}
<select name="company">
{html_options options=$vals selected=$selected_id}
select>

La diferencia con el primer caso de "solo html" es que lo estamos haciendo en la plantilla y no es público, y tampoco lo estamos haciendo del lado de PHP ya que toda la parte de generado de html era responsabilidad de Smarty (como una separación de capas).

Siguiendo con la evolución...

Nos pasamos a Zend Framework y usamos "Vistas"

Las vistas son como al principio de nuestra era, código html donde se embebe código PHP de la siguiente forma (un mix entre PHP embebido y sistema de plantillas).

Y volvemos al principio, he visto muchos proyectos que para poder hacer seguimiento de lo que generan de html tienen comentarios públicos html por todos lados, por lo que mi sugerencia final es... hagamos los comentarios dentro de la la vista, dentro del código PHP embebido y no dejemos expuestos nuestros comentarios internos.

Existen también herramientas que limpian el código, lo compactan y hasta te lo ofuscan, bien podrían ser una alternativa.

Pero la idea es esa, trata de no dejar comentarios que los pueda leer todo el mundo, sé ordenado y limpio. En lo personal cuando voy a ver páginas de diseño web que se ufanan de seguir "estándares", descubrir luego tablas o comentarios del tipo "abre tabla", "cierra tabla", etc, no me dejan muy tranquilo.

¿Qué opinas? ¿cuales son tus prácticas? ¿o no te importa que puedan descubrir leyendo el código de tu sitio? ;-)

Martin Fowler: "Código como documentación"

Releyendo algunos artículos de Martin Fowler (gurú/pensador relacionado con Análisis & Diseño en POO) caigo en este artículo que, fuera de no ser tan técnico, considero un tema base a tratar en los equipos de desarrollo como así también sobre cómo se podría aumentar la calidad del código de un desarrollador que se considere "profesional".

En lo personal prefiero ser siempre "simple", clarificar lo suficiente el código como para que hasta un novato pueda entenderlo y esto no me hace menos "experto" por hacer código "entendible".

Lo que hay que evitar es la "sobre-ingeniería", es decir, ser complejos por el simple hecho que nuestra mente sea -tal vez- un poco más rápida que el resto, o simplemente, porque llegamos a tal grado de "optimización temprana" que creemos que nuestra calidad es elevada cuando "resumimos" 50 líneas en unas pocas 5.

Nota al margen: tanto "sobre-ingeniería" como "optimización temprana" son dos males detectados en la ingeniería de software y deben evitarse.

Algunos ejemplos de lo histérico que puedo llegar a ser ;-). Tengo la costumbre inconsciente de:

Separar las sentencias relacionadas entre sí como si fueran párrafos de un artículo: veo a muchos desarrolladores que toman un método de una clase y en todo su contenido no hay una sola línea de separación, todo junto, todo "pegado". Lo primero que hago es empezar a separar como párrafos de un artículo: cuando las líneas de código están relacionadas, van juntas ("punto y seguido"), pero cuando las líneas tratan otro tema agrego una línea en blanco ("punto y aparte"). A mi me costaría leer un libro o un artículo que tiene contenido sin separar, ¿por qué no me pasaría eso con el código de un sistema?
Evitar los "elseif" porque anidar condiciones genera un código difícil de seguir, ya que tenemos que estar evaluando cada condición y todos sus caminos alternos. Si no quedara otra simplificación, trato de cambiar el elseif por un simple else y coloco dentro un "if" aparte y agregarles lineas de separación. En parte está relacionado con el punto anterior (no mejora la lógica pero sí su lectura y entendimiento).
Inmediatamente eliminar cualquier "número mágico", técnica de refactoring que dice algo así como "sustituir todos los códigos numéricos que hay por todo nuestro sistema y cambiarlo por una constante que lo describa", lo cual ya evita que tengamos que hacer un comentario antes del "número mágico".
Cambiar los nombres de variables y hacerlas más descriptivas, sin importar lo largas que me queden: si el caso es muy obvio, no tengo problemas de agregar una variables del tipo "ret" o "retorno", pero en el caso donde lo obvio es peligroso, o donde no es tan obvio, trato que las variables sean tan descriptivas que no haga falta agregar un comentario para explicar para qué sirven, y el lugar más indicado es con los parámetros de un método.
Abrir el código en varias líneas hasta que sea entendible: no tengo pudor en ampliar una línea de código en varias hasta que quede claro, aún sabiendo que puedo yo mismo entenderla con una sola línea. Lo importante, otra vez, no es si solo yo lo entiendo, es si el que viene detrás puede hacerlo, y esto es fundamental para trabajar en equipo y que todos seamos productivos.

Tan malo es hacer código que nosotros mismos nos cueste entender dentro de unos meses, como ser los únicos que lo puedan entender. Un código de alta calidad es el código que todos pueden entender, y hay que comprender que en algún momento u otro, vamos a trabajar en equipo con otra persona, y el código, además de ser entendible para nosotros poder trabajar de forma productiva, debe poder ser entendido por los demás.

Experto es quién hace código entendible, y experto es quién entiende la diferencia entre "código de calidad" y el que no lo es.

Y ahí entra la disciplina "refactoring" que busca, sin cambiar de funcionalidad, que el código mejore su calidad.

¿Y tú, haces código entendible para los demás, para ti, o para nadie? ;-)

Presentación: "Buenas Prácticas de Desarrollo en PHP"

Hace un tiempo que vengo recomendando esta presentación como punto de partida para definir un estándar de desarrollo en una empresa. En ambientes Java no se discute quién define los estándares, es la empresa Sun y a nadie se le ocurriría inventar el suyo propio. Además, en el mundo Java existen estándares para todo, desde la codificación, forma de programar, etc.

php development best practices - Upload a Document to Scribd

En el lado opuesto del mundo estamos nosotros, los del "Mundo PHP", donde cada cual tiene su propio estándar y programa "como quiere" (con todos los problemas que esto acarrea). Para evitarlo, lo mejor que podemos hacer es seguir los lineamientos generales que se desprenden de los documentos de Zend.

Y esta es una buena presentación por donde empezar.

En lo personal, al principio, me costó usar la "llave inicial" de clases y métodos al mismo nivel que la "llave de cierre" (al estilo programación "C"), pero como bien dice este material:

"No eres tan especial como para crear tu propio estándar"

Así que me acostumbré. Mi consejo es: úsalo! y no pierdas el tiempo en definir cómo se hace tal o cual cosa, pierde el tiempo con "problemas nuevos".

Más material: