¿Puede el código comentado ser una documentación valiosa?

Escribí el siguiente código:

if (boutique == null) {
    boutique = new Boutique();

    boutique.setSite(site);
    boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo());
    boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());
    boutique.setNom(fluxBoutique.getNom());
    boutique.setSelected(false);
    boutique.setIdWebSC(fluxBoutique.getId());
    boutique.setDateModification(new Date());

    boutiqueDao.persist(boutique);
} else {
    boutique.setSite(site);
    boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo());
    boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());
    boutique.setNom(fluxBoutique.getNom());
    //boutique.setSelected(false);
    boutique.setIdWebSC(fluxBoutique.getId());
    boutique.setDateModification(new Date());

    boutiqueDao.merge(boutique);
}

Hay una línea comentada aquí. Pero creo que aclara el código al hacer obvio cuál es la diferencia entre ify else. La diferencia es aún más notable con el resaltado de color.

¿Puede ser una buena idea comentar código como este?

La mayoría de las respuestas se centran en cómo refactorizar este caso específico, pero permítanme ofrecer una respuesta general de por qué el código comentado suele ser malo:

Primero, el código comentado no se compila. Esto es obvio, pero significa que:

1. El código podría incluso no funcionar.

2. Cuando las dependencias del comentario cambien, obviamente no se romperá.

El código comentado es mucho "código muerto". Cuanto más tiempo permanezca allí, más se pudre y proporciona cada vez menos valor al próximo desarrollador.

En segundo lugar, el propósito no está claro. Realmente necesita un comentario más largo que proporcione el contexto de por qué hay líneas comentadas al azar. Cuando veo solo una línea de código comentada, tengo que investigar cómo llegó allí solo para entender por qué llegó allí. ¿Quien lo escribió? ¿Qué compromiso? ¿Cuál fue el mensaje / contexto de confirmación? Etcetera

Considere alternativas:

• Si el objetivo es proporcionar ejemplos del uso de una función / api, proporcione una prueba unitaria. Las pruebas unitarias son código real y se romperán cuando ya no sean correctas.
• Si el propósito es preservar una versión anterior del código, use el control de origen. Prefiero verificar una versión anterior y luego alternar los comentarios en toda la base de código para "revertir" un cambio.
• Si el propósito es mantener una versión alternativa del mismo código, use el control de origen (nuevamente). Para eso están las ramas, después de todo.
• Si el propósito es aclarar la estructura, considere cómo puede reestructurar el código para hacerlo más obvio. La mayoría de las otras respuestas son buenos ejemplos de cómo podría hacer esto.

El mayor problema con este código es que duplicó esas 6 líneas. Una vez que eliminas esa duplicación, ese comentario es inútil.

Si crea un boutiqueDao.mergeOrPersistmétodo, puede volver a escribir esto como:

if (boutique == null) {
    boutique = new Boutique();
    boutique.setSelected(false);
}

boutique.setSite(site);
boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo());
boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());
boutique.setNom(fluxBoutique.getNom());
boutique.setIdWebSC(fluxBoutique.getId());
boutique.setDateModification(new Date());

boutiqueDao.mergeOrPersist(boutique);

El código que crea o actualiza un determinado objeto es común, por lo que debe resolverlo una vez, por ejemplo, creando un mergeOrPersistmétodo. Ciertamente no debe duplicar todo el código de asignación para esos dos casos.

Muchos ORM han incorporado soporte para esto de alguna manera. Por ejemplo, podrían crear una nueva fila si ides cero y actualizar una fila existente si idno es cero. La forma exacta depende del ORM en cuestión, y como no estoy familiarizado con la tecnología que está utilizando, no puedo ayudarlo con eso.

Si no desea crear un mergeOrPersistmétodo, debe eliminar la duplicación de alguna otra manera, por ejemplo, mediante la introducción de una isNewBoutiquebandera. Puede que no sea bonito, pero sigue siendo mucho mejor que duplicar toda la lógica de asignación.

bool isNewBoutique = boutique == null;
if (isNewBoutique) {
    boutique = new Boutique();
    boutique.setSelected(false);
}

boutique.setSite(site);
boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE + fluxBoutique.getLogo());
boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE + fluxBoutique.getUrl());
boutique.setNom(fluxBoutique.getNom());
boutique.setIdWebSC(fluxBoutique.getId());
boutique.setDateModification(new Date());

if (isNewBoutique)
    boutiqueDao.persist(boutique);
else
    boutiqueDao.merge(boutique);

Esta es una idea absolutamente horrible . No deja claro cuál es la intención. ¿El desarrollador comentó la línea por error? Para probar algo? ¡¿Que esta pasando?!

Aparte del hecho de que veo 6 líneas que son absolutamente iguales en ambos casos. Por el contrario, debe evitar la duplicación de este código. Entonces será más claro que, en un caso, también se llama a setSelected.

No, es una idea terrible. Basado en ese código, los siguientes pensamientos vienen a mi mente:

• Esta línea está comentada porque el desarrollador la estaba depurando y olvidó restaurar la línea a su estado anterior
• Esta línea se comenta porque una vez fue parte de la lógica de negocios, pero ya no es el caso
• Esta línea se comenta porque causó problemas de rendimiento en la producción y el desarrollador quería ver cuál era el impacto en un sistema de producción.

Después de ver miles de líneas de código comentado, ahora estoy haciendo lo único sensato cuando lo veo: lo elimino de inmediato.

No hay una razón razonable para registrar el código comentado en un repositorio.

Además, su código usa mucha duplicación. Le sugiero que optimice eso para la legibilidad humana lo antes posible.

Solo me gustaría agregar a la respuesta de CodesInChaos, señalando que puede refactorizarlo aún más en pequeños métodos . Compartir la funcionalidad común por composición evita los condicionales:

function fill(boutique) {    
  boutique.setSite(site);
  boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo());
  boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());
  boutique.setNom(fluxBoutique.getNom());
  boutique.setIdWebSC(fluxBoutique.getId());
  boutique.setDateModification(new Date());
}    

function create() {
  boutique = new Boutique();      
  fill(boutique);
  boutique.setSelected(false);
  return boutiqueDao.persist(boutique);
}

function update(boutique) {
  fill(boutiquie);
  return boutiquieDao.merge(boutique); 
}

function createOrUpdate(boutique) {
  if (boutique == null) {
    return create();
  }
  return update(boutique);  
}

Si bien esto claramente no es un buen caso para el código comentado, hay una situación que creo que lo justifica:

// The following code is obvious but does not work because of <x>
// <offending code>
<uglier answer that actually does work>

Es una advertencia para quien lo vea más tarde que la mejora obvia no lo es.

Editar: estoy hablando de algo pequeño. Si es grande, explica en su lugar.

En este ejemplo específico, encuentro que el código comentado es muy ambiguo, en gran parte por las razones descritas en la respuesta de Dibkke . Otros han sugerido formas en que podría refactorizar el código para evitar incluso la tentación de hacerlo, sin embargo, si eso no es posible por alguna razón (por ejemplo, las líneas son similares, pero no lo suficientemente cercanas), agradecería un comentario como:

// No es necesario anular la selección de esta boutique porque [LO QUE]

Sin embargo, creo que hay algunas situaciones en las que dejar el código (o incluso agregar comentarios) no es reprensible. Cuando se usa algo como MATLAB o NumPY, a menudo se puede escribir código equivalente que 1) itera sobre una matriz, procesando un elemento a la vez o 2) opera toda la matriz a la vez. En algunos casos, este último es mucho más rápido, pero también mucho más difícil de leer. Si reemplazo algún código con su equivalente vectorizado, inserto el código original en un comentario cercano, como este:

%% El siguiente código vectorizado hace esto:

% for ii in 1:N
%    for jj in 1:N
%      etc.

% pero la versión de matriz se ejecuta ~ 15 veces más rápido en la entrada típica (MK, 03/10/2013)

Obviamente, uno debe tener cuidado de que las dos versiones realmente hagan lo mismo y que el comentario permanezca sincronizado con el código real o se elimine si el código cambia. Obviamente, las advertencias habituales sobre la optimización prematura también se aplican ...

La única vez que vi un código comentado que fue útil fue en los archivos de configuración, donde se proporciona el código para cada opción, pero comentado, lo que hace que sea fácil habilitar la configuración simplemente eliminando los marcadores de comentarios:

## Enable support for mouse input:
# enable_mouse = true

En este caso, el código comentado ayuda a documentar todas las opciones disponibles y cómo usarlas. También es convencional usar los valores predeterminados en todas partes, por lo que el código también documenta la configuración predeterminada.

En términos generales, el código solo se documenta a sí mismo a la persona que lo escribió. Si se requiere documentación, escriba la documentación. Es inaceptable esperar que un desarrollador nuevo en una base de código fuente se siente a leer miles de líneas de código para intentar descubrir desde un alto nivel lo que está sucediendo.

En este caso, el propósito de la línea de código comentada es mostrar la diferencia entre dos instancias de código duplicado. En lugar de intentar documentar sutilmente la diferencia con un comentario, reescribe el código para que tenga sentido. Luego, si todavía siente que es necesario comentar sobre el código, escriba un comentario apropiado.

No, el código comentado se vuelve obsoleto, y pronto es peor que inútil, a menudo es dañino, ya que consolida algunos aspectos de la implementación, junto con todos los supuestos actuales.

Los comentarios deben incluir detalles de la interfaz y la función prevista; "función prevista": puede incluir, primero intentamos esto, luego lo intentamos, luego fallamos de esta manera.

Los programadores que he visto tratar de dejar las cosas en los comentarios simplemente están enamorados de lo que han escrito, no quieren perderlo, incluso si no está agregando nada al producto terminado.

Puede ser en casos muy raros, pero no como lo ha hecho. Las otras respuestas han explicado bastante bien las razones de eso.

Uno de los casos raros es una especificación de RPM de plantilla que usamos en mi tienda como punto de partida para todos los paquetes nuevos, en gran medida para asegurarnos de que no quede nada importante. La mayoría, pero no todos nuestros paquetes tienen un tarball que contiene fuentes que tiene un nombre estándar y se especifica con una etiqueta:

Name:           foomatic
Version:        3.14
 ...
Source0:        %{name}-%{version}.tar.gz

Para los paquetes sin fuentes, comentamos la etiqueta y colocamos otro comentario encima para mantener el formato estándar e indicar que alguien se detuvo y pensó en el problema como parte del proceso de desarrollo:

Name:           barmatic
Version:        2.71
 ...
# This package has no sources.
# Source0:        %{name}-%{version}.tar.gz

No agrega código que sabe que no se usará porque, como lo han cubierto otros, podría confundirse con algo que pertenece allí. Puede. sin embargo, sea útil para agregar un comentario que explique por qué falta el código que uno esperaría:

if ( condition ) {
  foo();
  // Under most other circumstances, we would do a bar() here, but
  // we can't because the quux isn't activated yet.  We might call
  // bletch() later to rectify the situation.
  baz();
}

La aplicación no utiliza el código comentado, por lo que debe ir acompañado de más comentarios que indiquen por qué no se está utilizando. Pero dentro de ese contexto, no son situaciones donde el código de salida comentado puede ser de utilidad.

Lo que me viene a la mente es un caso en el que resuelve un problema utilizando un enfoque común y atractivo, pero luego resulta que los requisitos de su problema real son ligeramente diferentes de ese problema. Especialmente si sus requisitos requieren mucho más código, la tentación de los encargados de "optimizar" el código utilizando el enfoque anterior probablemente será fuerte, pero hacerlo solo traerá de vuelta el error. Mantener la implementación "incorrecta" en los comentarios ayudará a disipar esto, porque puede usarla para ilustrar exactamente por qué ese enfoque es incorrecto en esta situación.

Esta no es una situación que pueda imaginar que ocurra muy a menudo. Por lo general, debería ser suficiente explicar las cosas sin incluir una implementación de muestra "incorrecta". Pero puedo imaginar un caso en el que eso no es suficiente, por lo tanto, dado que la pregunta es si puede ser útil, sí, puede serlo. Simplemente no la mayor parte del tiempo.

Esto no se ve bien amigo.

El código comentado es ... simplemente no es código. El código es para la implementación de la lógica. Hacer un código más legible en sí mismo es un arte. Como @CodesInChaos ya ha sugerido que las líneas de código repetitivas no son una muy buena implementación de la lógica .

¿Realmente crees que un verdadero programador preferirá la legibilidad sobre la implementación lógica? (por cierto, tenemos comentarios y 'complementos' para poner en nuestra representación lógica).

En lo que a mí respecta, uno debería escribir un código para el compilador y eso es bueno, si 'entiende' ese código. Para la legibilidad humana Los comentarios son buenos, para los desarrolladores (a largo plazo), para las personas que reutilizan ese código (por ejemplo, probadores).

De lo contrario, puede probar algo más flexible aquí, algo como

boutique.setSite (sitio) se puede reemplazar con

setsiteof.boutique (sitio). Hay diferentes aspectos y perspectivas de OOP a través de los cuales puede aumentar la legibilidad.

Si bien este código parece ser muy atractivo al principio y uno puede pensar que ha encontrado una forma de legibilidad humana, mientras que el compilador también hace su trabajo perfectamente, y todos comenzamos a seguir esta práctica, dará lugar a un archivo borroso que será menos legible a tiempo y más complejo, ya que se expandirá hacia abajo.