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.
Visão Geral
Import HTML Content
Conteúdo das Ferramentas
Tarefas