Para que los comentarios sean exactos y no falte contenido, tome en cuenta algunos consejos:

• Evite palabras ambiguas
  
  
  

Cuidado con el pronombre "él" verifique si queda claro a cuál sustantivo se refiere.

 Ejemplo:

// Inserta el dato en el caché, pero verifica si es demasiado grande.

En este ejemplo no está claro si se verificará el tamaño del caché o del dato que se insertará.

• Verifique si todo el comportamiento de la función está claro (no deje funciones o detalles ocultos). Si la función promete hacer una cosa, pero a la mitad del camino ejecuta otra tarea, esta subtarea debe describirse en los comentarios para que quién utilice la función sepa todo lo que esta ejecuta, y así evitar sorpresas desagradables en el comportamiento del sistema.

• Condense la información en palabras y expresiones técnicas estándares. Aproveche que los futuros lectores serán técnicos y no neófitos y utilice expresiones estándares para designar un comportamiento conocido.

Ejemplo:

en lugar de

// Esta clase almacena la misma información que está en la base de datos,

// pero se utiliza para desempeño. Cuando se lea esta clase,

// primero verificará si los campos existen y, en caso afirmativo,

// retornará sus valores, de lo contrario, leerá de la base de datos y almacenará

// los valores en los campos de la clase para una próxima oportunidad.

simplemente puede escribirse

// Esta clase actúa como un nivel de caché para la base de datos.