1. Comenta a varios niveles
Comenta los distintos bloques de los que se compone tu código, aplicando un criterio uniforme y distinto para cada nivel. Puedes, por ejemplo, seguir un modelo como:
- En cada clase, incluir una breve descripción, su autor y fecha de última modificación
- Por cada método, una descripción de su objeto y funcionalidades, así como de los parámetros y resultados obtenidos
En realidad, lo importante es ceñirse a unas normas (comúnmente aceptadas si se trata de trabajo en equipo) y aplicarlas siempre. Las reglas concretas pueden ser elegidas a la conveniencia de cada cual.
Obviamente, una solución bastante aceptable e incluso aconsejable es utilizar las convenciones y herramientas (como XML en C# ó Javadoc para el mundo Java) que ayudan y facilitan esta tarea.
2. Usa párrafos comentados
Como complemento al punto anterior, es recomendable dividir un bloque de código extenso en “párrafos” que realicen una tarea simple, e introducir un comentario al principio de forma que se guíe al lector, precediéndolos, además, de una línea en blanco que ayude a separar cada uno del anterior.
...
// Comprobamos si todos los datos
// son correctos
foreach (Record record in records)
{
if (rec.checkStatus()==Status.OK)
{
...
}
}
// Ahora pasamos a realizar las
// transacciones
Context ctx = new ApplicationContext();
ctx.BeginTransaction();
...
3. Tabula por igual los comentarios de líneas consecutivas
Si tenemos un bloque de líneas de código donde existe por cada una de ellas un comentario, es buena costumbre tabularlos todos a la misma posición, de forma que quedarán alineados y serán más sencillos de leer, sobre todo si forman parte de la misma frase.
const MAX_ITEMS = 10; // Número máximo de paquetes
const MASK = 0x1F; // Máscara de bits TCP
Ojo a las tabulaciones. Hay editores que usan el carácter ASCII (9) y otros, en cambio, lo sustituyen por un número determinado de espacios, que suelen variar según las preferencias personales del desarrollador. Lo mejor es usar espacios simples o asegurarse de que esto es lo que hace el IDE correspondiente.
4. No insultes la inteligencia del lector
Debemos evitar comentarios absurdos como:
if (a == 5) // Si a vale cinco, ...
counter = 0; // ... ponemos el contador a cero
...
Este exceso necesita mucho tiempo a la hora de su creación, lo necesitará para su mantenimiento y, además, la mayoría de las veces distraerá al lector con detalles que no es necesario conocer o que pueden ser deducidos echando un vistazo al código.
5. Sé correcto
Evita comentarios del tipo “ahora compruebo que el estúpido usuario no haya introducido un número negativo”, o “este parche corrije el efecto colateral producido por la patética implementación del inepto desarrollador inicial”.
El uso de este tipo de comentarios no dice nada a favor de su creador, y, además, nunca se sabe quién los va a leer en el futuro. Emarts, en “Sapos, culebras y código fuente” muestra ejemplos de comentarios de este tipo.
Otro tema relacionado y, a mi entender, igualmente importante: cuida la ortografía. El hecho de que los comentarios no se vean desde el exterior no implican que puedas descuidarlos. Una ortografía correcta mejora la calidad de la expresión escrita y, por tanto, de la comunicación, que es de lo que se trata.
6. No pierdas el tiempo
No comentes si no es necesario, no escribas nada más que
Twittealo!! 
Compartelo en Facebook!
Etiquetas:
Arte,
Beneficios,
BIOS,
Bj,
Blog,
Blogs,
C,
Calidad,
Cambio,
CD,
Cero,
Chiste,
Cliente,
Comentarios,
Consejos,
Creador,
Día,
Diseño,
Escritura,
Final,
Futuro,
Google,
Herramienta,
html,
Intro,
Java,
Lector,
Lenguaje,
Mac,
Mantenimiento,
Meme,
Palabras,
Pantalla,
Paquetes,
Personal,
Personales,
Poster,
Programa,
Programación,
Programador,
Programadores,
Programas,
RAM,
RC,
Realidad,
Record,
Referencia,
Software,
solución,
Tema,
Tiempo,
USA,
Vida,
Vista,
Wiki,
Wikipedia,
XP
, he visto que hay muy buenos blogs mujeres pero no tengo el placer de conocer a ninguna
), de manera que el sitio original es enlazado desde otros sitios web con la finalidad de recibir alguna que otra visita o simplemente como un pasatiempo.
