Histórico da Página

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,

...

simplemente puede escribirse

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