Buenas prácticas de programación

[roman]

Empezado por razonasistemas

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.

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

[[AzidRain]]

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.

[[Al González]]

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.

[[Delphius]]

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,

[[ElKurgan]]

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

Saludos

[razonasistemas]

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

[[AzidRain]]

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.