comments - good - how to comment code
¿Cuáles son sus "reglas duras" para comentar su código? (21)
La documentación es como el sexo; cuando es bueno, es muy, muy bueno, y cuando es malo, es mejor que nada
He visto las otras preguntas pero todavía no estoy satisfecho con la forma en que se cubre este tema .
Me gustaría extraer una lista eliminada de cosas para verificar los comentarios en una inspección del código.
Estoy seguro de que la gente dirá cosas que simplemente se cancelarán entre sí. Pero bueno, tal vez podamos construir una lista para cada campamento. Para aquellos que no hacen ningún comentario la lista será muy corta :)
Agrego 1 comentario a un bloque de código que resume lo que estoy haciendo. Esto ayuda a las personas que buscan una funcionalidad específica o una sección de código.
Comenta cualquier algoritmo o proceso complejo que no se pueda descifrar a primera vista.
Firmo mi código
Al implementar un RFC u otra especificación de protocolo, comente las máquinas de estado / controladores de eventos / etc. con la sección de la especificación a la que corresponden. Asegúrese de listar la versión o fecha de la especificación, en caso de que se revise más tarde.
Creo un bloque de comentarios al comienzo de mi código, que enumera el propósito del programa, la fecha en que fue creado, cualquier información de licencia / copyright (como GPL) y el historial de la versión.
A menudo, comparo mis importaciones si no es obvio por qué se importan, especialmente si el programa general no parece necesitar las importaciones.
Agrego un docstring a cada clase, método o función, describiendo cuál es el propósito de ese bloque y cualquier información adicional que considero necesaria.
Normalmente tengo una línea de demarcación para las secciones relacionadas, por ejemplo, la creación de widgets, variables, etc. Como utilizo SPE para mi entorno de programación, resalta automáticamente estas secciones, facilitando la navegación.
Agrego los comentarios de TODO como recordatorios mientras estoy codificando. Es una buena manera de recordarme a mí mismo para refactorizar el código una vez que se haya verificado que funciona correctamente.
Finalmente, comento líneas individuales que pueden necesitar alguna aclaración o que de otra manera necesiten algunos metadatos para mí en el futuro u otros programadores.
Personalmente, odio mirar el código e intentar descubrir qué se supone que debe hacer. Si alguien pudiera escribir una oración simple para explicarlo, la vida es más fácil. Código de auto-documentación es un nombre inapropiado, en mi libro.
Cuando redacte comentarios, deténgase, reflexione y pregúntese si puede cambiar el código para que los comentarios no sean necesarios. ¿Podría cambiar algunos nombres de variables, clases o métodos para aclarar las cosas? ¿Alguno assert u otras verificaciones de error codificarían sus intenciones o expectativas? ¿Podría dividir algunas secciones largas de código en métodos o funciones claramente nombrados? Los comentarios son a menudo un reflejo de nuestra incapacidad para escribir (a-hem, código) claramente. No siempre es fácil escribir claramente con lenguajes de computadora, pero tómate un tiempo para probar ... porque el código nunca miente.
PD. El hecho de que use comillas alrededor de "reglas duras" es revelador. Las reglas que no se aplican no son "reglas duras" y las únicas reglas que se aplican son el código.
Documentaré cada clase, cada función, cada variable dentro de una clase. Los DocBlocks simples son el camino a seguir.
En general, escribiré estos docblocks más para la documentación de API automatizada que cualquier otra cosa ...
Por ejemplo, la primera sección de una de mis clases de PHP
/**
* Class to clean variables
*
* @package Majyk
* @author Martin Meredith <[email protected]>
* @licence GPL (v2 or later)
* @copyright Copyright (c) 2008 Martin Meredith <[email protected]>
* @version 0.1
*/
class Majyk_Filter
{
/**
* Class Constants for Cleaning Types
*/
const Integer = 1;
const PositiveInteger = 2;
const String = 3;
const NoHTML = 4;
const DBEscapeString = 5;
const NotNegativeInteger = 6;
/**
* Do the cleaning
*
* @param integer Type of Cleaning (as defined by constants)
* @param mixed Value to be cleaned
*
* @return mixed Cleaned Variable
*
*/
Pero luego, a veces también documentaré un código significativo (de mi init.php
// Register the Auto-Loader
spl_autoload_register("majyk_autoload");
// Add an Exception Handler.
set_exception_handler(array(''Majyk_ExceptionHandler'', ''handle_exception''));
// Turn Errors into Exceptions
set_error_handler(array(''Majyk_ExceptionHandler'', ''error_to_exception''), E_ALL);
// Add the generic Auto-Loader to the auto-loader stack
spl_autoload_register("spl_autoload");
Y, si no se explica por sí mismo por qué algo hace algo de cierta manera, comentaré que
El único lugar garantizado que dejo comentarios: secciones TODO . El mejor lugar para realizar un seguimiento de las cosas que necesitan volver a trabajar está ahí en el código.
Escribí un artículo completo sobre malos comentarios. Disfruta :)
Escriba el código legible que se explica por sí mismo tanto como sea posible. Agregue comentarios cada vez que tenga que escribir un código que sea demasiado complejo para comprenderlo de un vistazo. También agregue comentarios para describir el propósito comercial detrás del código que escribe, para que sea más fácil mantenerlo / refactorizarlo en el futuro.
Los comentarios que escribe pueden ser reveladores sobre la calidad de su código. Incontables veces eliminé comentarios en mi código para reemplazarlos por un código mejor y más claro. Para esto sigo un par de reglas anti-comentarios:
- Si su comentario simplemente explica una línea de código, debe dejar que esa línea de código hable por sí misma o dividirla en componentes más simples.
- Si su comentario explica un bloque de código dentro de una función, probablemente debería estar explicando una nueva función en su lugar.
Esas son realmente la misma regla repetida para dos contextos diferentes.
Las otras reglas más normales que sigo son:
- Cuando utilice un lenguaje de tipado dinámico, documente las expectativas que las funciones importantes tienen sobre sus argumentos, así como las expectativas que las personas que llaman pueden hacer sobre los valores de retorno. Las funciones importantes son aquellas que tendrán llamadas que no sean locales.
- Cuando su lógica es dictada por el comportamiento de otro componente, es bueno documentar lo que su comprensión y expectativas de ese componente son.
Me enfoco en el por qué . Porque lo que a menudo es fácil de leer. Los TODO también son geniales, ahorran mucho tiempo.
Y documentaré las interfaces (por ejemplo, formatos de archivo).
No hay reglas duras: las reglas duras conducen al dogma y las personas generalmente siguen el dogma cuando no son lo suficientemente inteligentes como para pensar por sí mismos.
Las pautas que sigo:
1 / Los comentarios dicen lo que se está haciendo, el código dice cómo se está haciendo, no duplique su esfuerzo.
2 / Los comentarios deben referirse a bloques de código, no a cada línea. Eso incluye comentarios que explican archivos completos, funciones completas o simplemente un fragmento de código complicado.
3 / Si creo que volvería en un año y no entiendo la combinación código / comentario, entonces mis comentarios aún no son lo suficientemente buenos.
Normalmente comento un método antes de escribirlo. Escribiré una o dos líneas de comentarios para cada paso que debo tomar dentro de la función, y luego escribiré el código entre los comentarios. Cuando termine, el código ya está comentado.
La gran parte de eso es que se comenta antes de escribir el código, por lo que no hay suposiciones irrazonables sobre el conocimiento previo en los comentarios; Yo mismo no sabía nada sobre mi código cuando lo escribí. Esto significa que tienden a ser fáciles de entender, como deberían ser.
Preámbulos solo; declara la responsabilidad única de una clase, cualquier nota o comentario, y registro de cambios. En cuanto a los métodos, si algún método necesita comentarios sustanciales, es hora de refactorizar.
Si un comentario está desactualizado (no coincide con el código), bórrelo o actualícelo. Nunca dejes un comentario inexacto en su lugar.
Tengo una regla simple sobre los comentarios: su código debe contar la historia de lo que está haciendo; sus comentarios deben contar la historia de por qué lo está haciendo.
De esta manera, me aseguro de que quien herede mi código pueda comprender la intención detrás del código.
Una gran regla para comentarios: si está leyendo el código tratando de resolver algo, y un comentario en algún lugar le habría dado la respuesta, colóquelo ahí cuando sepa la respuesta .
Solo pasa ese tiempo investigando una vez .
Eventualmente sabrá a medida que escribe los lugares que necesita para dejar la orientación, y los lugares que son lo suficientemente obvios para estar solo. Hasta entonces, pasarás un tiempo rastreando tu código tratando de descubrir por qué hiciste algo :)
En mi opinión, TODO / TBD / FIXME etc. están bien para tener en el código que se está trabajando actualmente, pero cuando ve el código que no se ha tocado en 5 años y está lleno de ellos, se da cuenta de que es una bonita pésima manera de asegurarse de que las cosas se arreglen. En resumen, las notas de TODO en los comentarios tienden a permanecer allí . Es mejor usar un rastreador de errores si tiene cosas que necesitan ser reparadas en algún momento.
Hudson (servidor CI) tiene un gran complemento que busca TODO y anota cuántos hay en su código. Incluso puede establecer umbrales que hacen que la construcción se clasifique como inestable si hay demasiados.
Mi regla de oro favorita con respecto a los comentarios es: si el código y los comentarios no concuerdan, es probable que ambos sean incorrectos
Una cosa realmente importante para verificar cuando está revisando la documentación del encabezado (o lo que sea que llame el bloque que precede a la declaración del método) es que las directivas y advertencias son fáciles de detectar.
Las directivas son instrucciones de "do" o "do not do" que afectan al cliente: no llame desde el hilo de UI, no lo use en código de rendimiento crítico, llame a X antes de Y, libere valor de retorno después del uso, etc.
Las advertencias son cualquier cosa que podría ser una desagradable sorpresa: elementos de acción restantes, suposiciones y limitaciones conocidas, etc.
Cuando te centras en un método que estás escribiendo e inspeccionando, verás todo. Cuando un programador usa su método y otras treinta personas en una hora, no puede contar con una lectura completa. Puedo enviarte datos de investigación si estás interesado.
Escribimos un artículo sobre comentarios (en realidad, he hecho varios) aquí: http://agileinaflash.blogspot.com/2009/04/rules-for-commenting.html
Es realmente simple: los comentarios se escriben para decirle lo que el código no puede.
Esto da como resultado un proceso simple: - Escriba cualquier comentario que desee al principio. - Mejore el código para que el comentario se vuelva redundante - Elimine el comentario ahora redundante. - Solo código de confirmación que no tiene comentarios redundantes
- Comenta funciones públicas o protegidas con metacomentarios, y normalmente recuerdo las funciones privadas si recuerdo.
- Comente por qué existe un bloque de código suficientemente complejo (llamada de juicio). El por qué es la parte importante.
- Hago un comentario si escribo un código que creo que no es óptimo, pero lo dejo porque no puedo encontrar una forma más inteligente o sé que voy a refacturar más tarde.
- Hago un comentario para recordarme a mí mismo oa otros sobre la falta de funcionalidad o el próximo código de requisitos que no está presente en el código (TODO, etc.).
- Hago comentarios para explicar reglas comerciales complejas relacionadas con una clase o fragmento de código. Se me conoce por escribir varios párrafos para asegurarme de que el próximo chico / chica sepa por qué escribí una clase de cientos de líneas.