Lectura recomendada: Clean Code por Robert C. Martin.
En resumen, usted debe
uso
- nombres de variables/método/clase significativas,
- mantienen sus funciones/métodos de corta,
- tener cada clase y método de hacer una sola cosa,
- tener el código en cada método en el mismo nivel de abstracción.
No tema extraer expresiones incluso moderadamente complejas de if declaraciones; cuál es más claro para leer, esto
if (i >= 0 && (v.size() < u || d == e)) ...
o
if (foundNewLocalMaximum()) ...
(No tratar de encontrar algún significado en el primer fragmento de código, me acabo de inventar :-)
Los comentarios en código limpio casi nunca se necesitan. Las únicas excepciones que se me ocurren es si está utilizando alguna función oscura del lenguaje (por ejemplo, metaprogramación de plantillas C++) o algoritmo, y da una referencia a la fuente del método/algoritmo y sus detalles de implementación en un comentario.
La razón principal por la que cualquier otro tipo de comentarios no es muy útil a largo plazo es que el código cambia, y los comentarios tienden a no actualizarse junto con los cambios en el código correspondiente. Así que después de un tiempo el comentario no es simplemente inútil, pero es engañoso: te dice algo (notas de implementación, razonamiento sobre las elecciones de diseño, correcciones de errores, etc.) que se refiere a una versión del código que ya pasó, y tienes no tengo idea si ya es relevante para la versión actual del código.
Otra razón por la que creo que "el motivo por el que elegí esta solución" a menudo no vale la pena documentar en el código, es que la versión breve de dicho comentario casi siempre sería "porque creo que este es el mejor manera ", o una referencia a, por ejemplo, "The C++ Programming Language, ch. 5.2.1", y la versión larga sería un ensayo de tres páginas. Creo que un programador experimentado ve y entiende a menudo por qué el código se escribe así sin mucha explicación, y un principiante puede no entender incluso la explicación en sí misma: no vale la pena tratar de cubrir a todos.
Por último pero no menos importante, las pruebas de unidad IMO son casi siempre una mejor forma de documentación que los comentarios del código: las pruebas unitarias documentan su comprensión, suposiciones y razonamiento sobre el código bastante eficientemente, además se le recuerda automáticamente que las mantenga sincronizar con el código cada vez que los rompa (bueno, siempre que los ejecute con su compilación ...).
Duplicado: http://stackoverflow.com/questions/784250/is-it-possible-to-write-good-and-understandable-code-without-any-comments – tangens
Tenga en cuenta que el código no puede decirle por qué algo se hace de una manera particular, solo CÓMO. –
Es un mito que solo los comentarios pueden decir "por qué". A veces necesitas un comentario para eso, pero a menudo el código puede contar toda la historia. Mira, un comentario no está mal. Pero considere la necesidad de que los comentarios sean una señal de que el código podría, tal vez, hacerse más claro. –