Reglas para comentar código

Hace unos días fuí a parar a un enlace bastante interesante donde se enumeran diversos consejos para comentar código de la forma más elegante posible (autor José M. Aguilar). Resumen:

  1. Comenta a varios niveles: Al inicio de una clase, de un método, etc.
  2. Usa párrafos comentados: No redactar lineas kilométricas, utilizar párrafos.
  3. Tabula por igual los comentarios de líneas consecutivas: Si tenemos 2 líneas de código de longitudes diferentes y en cada una añadimos un comentario, que estos se encuentren alineados el uno respecto al otro.
  4. No insultes la inteligencia del lector: No comentar las obviedades.
  5. Sé correcto: Los comentarios ofensivos o las bromas no tienen porque ser del agrado de todo el mundo, hay que limitarse a comentar de forma neutral.
  6. No pierdas el tiempo: Estilo directo, conciso y claro.
  7. Utiliza un estilo consistente: Definir quien va a ser el destinatario de los comentarios (programadores expertos, usuarios, etc.) y redactar en consecuencia a través de todo el código.
  8. Para los comentarios internos usa marcas especiales: Por ejemplo, utilizar la palabra TODO siempre que quieras indicar que falta por implementar alguna característica.
  9. Comenta mientras programas: No dejes para mañana lo que puedas hacer hoy, de lo contrario te costara el doble y tendrá la mitad de calidad.
  10. Comenta como si fuera para tí mismo.
  11. Actualiza los comentarios a la vez que el código
  12. La regla de oro del código legible: Deja que el código hable por si mismo, de esta forma podrás minimizar los comentarios a escribir.

Os dejo con otro artículo que también habla del tema (y otro más). ¿Añadiríais algún otro consejo?

2 thoughts on “Reglas para comentar código

  1. En proposo un que jo miro d’aplicar habitualment: escriure primer els comentaris, i després el codi. M’ajuda a seguir aquell ordre lògic tan aplastant:
    1. pensar què vull fer (i escriure-ho com a comentari)
    2. fer-ho (escriure el codi)

Leave a Reply

Your email address will not be published. Required fields are marked *