Buenas prácticas de programación
 

Hola.

Me gustaría poder controlar la calidad del código fuente que, o bien creamos en la empresa, o bien subcontratamos.

Mi idea es poder descargar del repositorio de código (usando cvs o svn) los ficheros que se han añadido / modificado y comprobar si siguen una serie de criterios de buenas practicas de programación.

Los criterios que, de momento, se me ocurren son :

* Tamaño del fichero. Si se meten miles de lineas en un solo fichero, éste se convierte en ilegible.

* Tamaño de las funciones. Cuando estudiaba se decía que una función no debería ser mayor que el tamaño de la pantalla. Así que una función con mas de x lineas seria un criterio.

* Ratio mínimo de comentarios. Debería haber un ratio lineas_de_comentario / lineas_totales mínimo. Estos comentarios deberían de ser útiles, ya que hace años traté de instaurar un estilo de comentarios parecido al javadoc y me encontré con que la gente ponía como comentarios en un button.click, por ejemplo "@param sender componente que activa el evento" o "@return no se devuelven resultados" o sea, comentarios sin ningún valor.

* Comentarios en funciones. Si una función tiene mas de x lineas entonces es compleja y debería de tener en su cabecera un comentario explicando el funcionamiento.

Estas son las que se me han ocurrido. Si alguien tiene algún otro criterio o alguna idea le agradeceré mucho su comentario.

Por cierto, los lenguajes a tratar serían Delphi, Java, C# y ASP.

Saludos

Hola, bienvenido a clubdelphi :)
Abajo de esta página encontrarás varios enlaces que te pueden servir.

Pues hombre, tanto como sin ningún valor...

Los comentarios en javadoc tienen un formato muy específico, y uno de los requerimientos es el de especificar los parámetros y valor devuelto por cada método.

Toma en cuenta que tales comentarios se usan para generar documentación en automático. Si ves un listado de los métodos de una clase en un contexto ajeno al código en sí, puede resultar muy útil saber a primera vista qué parámetros recibe un método y si devuelve o no un valor.

Y, dado que este tipo de consideraciones son útiles para generar documentación, no es descabellado que parte de tus criterios de calidad del código fuente incluya el uso sistemático de comentarios de ese tipo.

// Saludos

Yo te puedo comentar que en cuanto a comentarios, mientras más mejor, sobre todo en funciones que el programador en cuestión desarrolló o diseño el solo. En esos casos también es muy deseable agregar un pequeño pseudocódigo que explique en palabras llanas que hace determinada función, sobre todo las muy complejas o que utilizan algoritmos que si bien son conocidos no son dominados por todo el mundo.

Los comentarios nunca van a sobrar (salvo los de verdad obvios).

Ahora bien, muchas veces en aras de la legibilidad del código se sacrifica el tiempo de "creatividad" del programador pues en lugar de concentrarse totalmente en hacer que lo que está desarrollando haga lo que tiene que hacer muchas veces pierde tiempo en ir comentando lo que va haciendo.

Aquí en el chinringuito lo que hacemos es que cada programador tiene vía libre para desarrollar siempre y cuando el resultado sea el requerido, una vez demostrada la validez del código, entonces sí, tiene que optimizarlo y documentarlo pero ya sabiendo que lo principal ya se cumplió. Es tan simple como "a ver, muéstrame que hace" y luego..."bien, ahora documéntalo y me enseñas como lo haces". Hasta ahora nos va funcionando y nos permite mantener la productividad sin sacrificar el estilo del código.

Y, aunque no se trata exactamente de lo planteado por razonasistemas, puede que esto le proporcione nuevas ideas (hablando de buenas prácticas de programación). :)

Saludos.

Pues si te quieres meter de lleno en lo que es y hace a la calidad y productividad basada en "mediciones" extraídas desde el código fuente entonces se sugiero que le dés más de una leída al libro "Ingeniería de software, un enfoque práctico" de Robert Presman. A lo largo del libro va presentando medidas, métricas e indicadores que pueden ayudarte a sacar algunas conclusiones.

Noto que has puesto demasiado énfasis en lo que es a comentarios. Tanto o más importante que disponer de un buen equilibrio en la cantidad de comentarios y en como uno documenta el código es la legibilidad del código.

Cuando se trabaja en grupo es más que importante tener reglas claras al momento de programar. Si algunos te van a escribir código en español y otros en inglés, o si uno le va a CamelCase y otros a NoMeImporTACAZEH o cosas por el estilo entonces hay un descontrol que ni te cuento.
Mucho mal que pese se debe poner orden en la casa y todos deben respetar un estilo y formato a seguir para que se puedan intercambiar ideas.
Eso de que cada quien tiene su estilo y que el otro se las arregle no va.

Si se define un criterio de nomeclatura, y unas pocas reglas de uso y buenas prácticas todos saldrán ganando y ninguno se sentirá que le cortan su propia manera de programar. Naturalmente, para llegar a esto debe haber una puesta de cada uno del equipo a fin de coordinar entre todos como se han de llevar las cosas.

Si estás interesado, hay herramientas que permiten generar documentación a base de comentarios desde el código, algo parecido a JavaDoc. Una de esas herramientas es DelphiCodeToDoc; hay otros proyectos similares a ese.

Saludos,

Yo siempre recomiendo el estupendo manual de estilo de Alexander Hristov... ¡Y además está en perfecto Español!

Saludos

Voy a comentarte algunas cosillas:

Lo que hace ilegible el código no es el tamaño, sino la documentación y el estilo. Si usas nombre con significados reales, bien formateado (por ejemplo, con CamelCase o usando_caracter_subrayado), bien indexado y con comentarios bien redactados, da igual cuán largo sea.

He visto funciones de pocas líneas en las que es imposible saber qué hacen y menos aún cómo lo hacen, sin embargo he visto funciones de varias páginas en las que el algoritmo está claro y diáfano.

Personalmente creo que limitar el tamaño "porque sí" es una tontería, aparte de que puede afectar al rendimiento al multiplicar las llamadas. Recuerda que cada llamada a método o función es tiempo extra, mayor cuantos más parámetros tengan.

A partir de Delphi 2007 existe la posibilidad de definir Metrics y Audits según el gusto de cada uno, basta con habilitar el project para UML en Model View y pinchar con el botón derecho sobre los diagramas generados ..

Me acordé cuando leí el comentario de Delphius de cuando en la universidad presenté un proyecto en un concurso (el cual por fortuna gané) y utilcé el modelo COCOMO para estimar los costos del mismo en caso de comercializarlo. Eran por ahí del '94 cuando lo hice y ni siquiera era Delphi. Ahora ya está en desuso ese modelo, con el advenimiento de la OOP y las enseñanzas de Don Grady Booch.

Delphi-To-Doc es bueno pero a mi juicio no iguala la calidad y facilidad de JavaDoc donde el propio IDE que utilices (Eclipse o Netbeans) reconoce los comentarios y te proporciona recordatorios de parámetros y demás cosas, simplemente no he encontrado algo parecido.

Al final, la documentación tiene como función principal explicar lo que el código hace, como lo hace y por qué lo hace así.

Lo que si es muy importante es estandarizar detalles en el estilo: Usar o no CamelCase, o subrayados, definir índices de ciclos a partir de "i,j,k..etc.", no utilizar variables de una sola letra, utilizar constantes siempre que un valor se repita más de una vez y colocarlas en una sola unidad para poder tenerlas a la mano en cualquier momento, etc.

Gracias a todos por contestarme.

Uno de los problemas que tenia era que, al haber subcontratado cosas, especialmente la programación web, pues no tenia acceso al codigo fuente de inmediato, sino una vez entregada y pagada la aplicacion.

Y nos encontrábamos con que el programa subcontratado funcionaba bien, porque cumplía sus funciones, pero luego, cuando había que hacer alguna modificación era una pesadilla :

* Código sin ninguna documentación.
* Algunos programas constaban de un único fichero enorme.
* Funciones larguísimas con el mismo código copiado y pegado.

Y no solo pasaba con lo subcontratado. En algunos desarrollos propios en Delphi o Java también me encontraba con alguna de estas barrabasadas.

Ayer me dedique a leer de cabo a rabo el libro que me recomendó elKurgan, y me he dado cuenta de que lo que yo buscaba es un software llamado analizador estático de código. Me he bajado uno llamado MonitorSource y voy a pelearme con el, a ver si puedo enlazarlo con el svn para poder hacer automáticamente el análisis que necesito.

Saludos

Un consejo, no subcontrates en esas condiciones pues estás a expensas de lo que el señor que contrates quiera o no hacer, además de que en efecto te entregará código espaguetti en la mayoría de los casos.

Aqui tambien subcontratamos cuando se trata de algún proyecto para el cual no tenemos personal que pueda realizarlo, pero la condición que ponemos siempre es tener acceso al código en todo momento se haya o no pagado (por eso firmamos un contrato) así podemos ir haciendo observaciones y podemos controlar todo el proceso de desarrollo.

En efecto hay gente que no le gusta y quiere entregarte todo hasta el final, pero afortunadamente también hay mucha gente que le da lo mismo mientras el pago sea justo y se cumpla. En algunos casos excepcionales otorgamos un bono adicional por calidad en el desarrollo.