¿Crees que el código se auto documenta? [cerrado]

Esta es una pregunta que me formularon hace muchos años como graduado en una entrevista de trabajo y me molesta de vez en cuando y nunca he encontrado una buena respuesta que me haya satisfecho.

El entrevistador en cuestión estaba buscando una respuesta en blanco y negro, no había término medio. Nunca tuve la oportunidad de preguntar sobre la razón detrás de la pregunta, pero tengo curiosidad por qué esa pregunta se le haría a un desarrollador y qué aprendería de una respuesta de sí o no.

Desde mi propio punto de vista, puedo leer Java, Python, Delphi, etc., pero si mi gerente se me acerca y me pregunta qué tan avanzado en un proyecto estoy y digo "El código está 80% completo" (y antes empiezas a derribarme, he escuchado esto pronunciado en un par de oficinas por desarrolladores), ¿cómo es exactamente eso autodocumentado? Disculpas si esta pregunta parece extraña, pero prefiero preguntar y obtener algunas opiniones al respecto para comprender mejor por qué se le haría a alguien en una entrevista.

Parcialmente.

El código que usa Big English Words puede autodocumentarse parcialmente, ya que los nombres de todas las funciones y variables pueden decirle lo que está haciendo. Pero probablemente no te dirá por qué.

Comparar:

a->b;
# what is b doing? what is the a object?

carEngine->startIgnition;
# much more clear what objects are involved

Pero aún no sabe por qué se está arrancando un automóvil. Por lo tanto, solo parcialmente. Es un poco terrible que su entrevistador esperara una respuesta en blanco y negro, a menos que su punto de vista en blanco y negro incluyera una muy fuerte tal vez.

No. El código en sí mismo no se documenta por sí mismo.

La razón es que el código establece CÓMO y no le importa POR QUÉ, que es lo que los humanos necesitan saber para mantener el código.

Por lo tanto, necesita comentarios adicionales que expliquen todos los POR QUÉ . Puede limitarlos dejando que sus nombres de variables incluyan alguna parte de las decisiones, pero no puede evitarlos.

El código apropiado te dice " cómo ". Los comentarios correctos te dicen " por qué " .

Por lo tanto, el código puede autodocumentarse de la forma en que se logran las cosas, pero no se puede suponer que documenta el motivo.

Si insisten en una respuesta en blanco y negro sin un término medio permitido, la respuesta es no.

La respuesta más completa es que el código debe autodocumentarse en la medida máxima que sea razonable, pero no hay una forma razonable de incluir algunos tipos de documentación en el código. Solo por ejemplo, el código podría hacer una buena documentación de qué información se recopila en el formulario A, qué en el formulario B y qué en el formulario C. En general, no intentará (y probablemente no debería) documentar las pruebas que muestran esa división los datos de esa manera redujeron los errores x% en comparación con (por ejemplo) usar solo dos formas en lugar de tres.

Cualquier cosa menos el fragmento de código más trivial puede beneficiarse de al menos alguna documentación externa.

Mi respuesta. En la mayor medida posible, debe esforzarse por hacer que su código se documente lo más posible. Hay muchas razones para esto. Cuando se escribe inicialmente, un promedio de una línea en 10 tiene un error. Los errores en el código tienden a ser encontrados y corregidos. Los errores en la documentación tienden a dejarse de lado. Y en el mantenimiento es común que el código y la documentación se separen.

Dicho esto, hay limitaciones en lo que se puede hacer al dejar claro el código. En esos casos, debe documentar.

¿Qué pasa con el caso en el que tiene la opción de documentar? Mi opinión es que el mantenimiento depende en gran medida de su organización. Si tiene excelentes desarrolladores de software y un riguroso proceso de revisión de código (como, por ejemplo, Google), entonces su proceso y las personas pueden ser tales que no necesita preocuparse por los comentarios que no se pueden mantener. En ese caso, un estilo mucho más lleno de comentarios tiene mucho sentido. (De hecho, Google tiene un estilo con muchos comentarios). Sin embargo, si tiene una organización más típica, desconfiaré mucho de cualquier comentario que vea, y espero que haya personas que crean al tratar de hacer que el código se auto documente. En esa situación, consideraré los comentarios como superfluos.

Para una conversación interesante sobre los méritos y desventajas de comentar, vea http://www.perlmonks.org/index.pl?node_id=65153 para una conversación antigua de la que formé parte. (Tenga en cuenta que, al mismo tiempo que tuvimos esa conversación, hubo un conjunto privado de chats que fueron más amigables. Siempre me he arrepentido de que solo la mitad más negativa de la conversación sea pública). Mis opiniones ya no coinciden exactamente con lo que pensaba entonces. , pero sigo pensando que la conversación vale la pena pensar.

Me parece que esta pregunta surge mucho, y a menudo tiene un fervor religioso al respecto. Aquí está mi opinión sobre esto ...

En un mundo ideal, se podría hacer la siguiente declaración:

El código debe escribirse de tal manera que se pueda seguir la lógica sin necesidad de comentarios.

Bien, esto es bastante justo, pero el problema es que no vivimos en un mundo ideal. Hay algunos problemas para lograr esta declaración ideal.

1. Los programadores a menudo no son los expertos en la industria contra la que están programando. Es bastante fácil entender una función como startEngine(Car car)(la mayoría) todos pueden entender lo que se pregunta aquí. Pero muévase al mundo real, y las cosas se ponen un poco más borrosas. Por ejemplo, la función getSess(String tid, String aid)sería perfectamente comprensible para un ingeniero de transporte que entendiera los sistemas DWDM, pero puede presentar un desafío para el nuevo programador que acaba de poner el proyecto. Los comentarios bien colocados pueden ayudar a facilitar la transición para comprender el código de manera oportuna.

2. Los programadores a los que se les pide que mantengan el código a menudo no son tan hábiles como los arquitectos originales del código. El programador original puede haber sido lo suficientemente hábil como para escribir un algoritmo rápido, sucinto y eficiente para realizar una tarea específica. Pero el programador encargado de mantener ese código puede tener dificultades para tratar de entender lo que está sucediendo. Los comentarios bien colocados pueden ayudar a facilitar la transición para comprender el código de manera oportuna.

3. ¿Cuántas veces has escrito un poco de código que luego te costó entender por qué lo hiciste, o incluso lo que estabas tratando de lograr? Todos hacemos eso de vez en cuando. Resolver un problema y producir una solución fácil de seguir a un problema a menudo son dos mentalidades diferentes. A menos que usted sea la persona que puede escribir código perfectamente desde el principio, a menudo realiza muchos pasos en falso con su código a medida que avanza. Es posible que tampoco pueda volver a este código por un tiempo. Los comentarios bien colocados pueden ayudar a facilitar la transición para comprender el código de manera oportuna.

4. Situaciones únicas requieren explicación. Por ejemplo, un programador puede preguntarse por qué se puso una pausa de 100 ms en un código que se comunica con un dispositivo DWDM. Informar al siguiente programador que se necesita una pausa porque el dispositivo es lento en la captación y puede perder el comando sería una información valiosa. Los comentarios bien colocados pueden ayudar a facilitar la transición para comprender el código de manera oportuna.

Bien escrito, el código de "autodocumentación" es un placer encontrarlo. Muy bien escrito, el código "autodocumentado", con comentarios informativos bien ubicados es un regalo del cielo, y un hallazgo muy raro.

Solo para dar argumentos en cada lado de la pregunta inicial:

Sí, el código es autodocumentado. Las variables, los métodos y los nombres de clase se pueden hacer para que sean fáciles de leer y comprender, de modo que esta sea una forma de autodocumentación. Puede haber algo dentro del estilo de código que proporciona documentación XML al final que se considera un procedimiento estándar. En otras palabras, es parte del trabajo del desarrollador proporcionar documentación que pueda estar entremezclada con el código.

No, el código no se documenta automáticamente. Las decisiones comerciales tomadas, las elecciones de diseño realizadas y otros factores no aparecerán en las líneas de código y deben escribirse fuera de la base del código. Por lo tanto, la documentación externa es necesaria y estos son ejemplos de ello.

Punto de pregunta: ¿Daría una respuesta parcial reconociendo las limitaciones de una respuesta o se inclinaría ciegamente hacia el lado que cree que es la mejor práctica? ¿Cuánta convicción tienes en tu respuesta si es un sí o un no? Podría verse como una pregunta estresante que está diseñada para hacer surgir a alguien que puede responder: "¿Qué ...? Esa es la pregunta más tonta que podrías hacerme. Me niego a responder eso porque insulta. mi inteligencia más allá de la creencia! " como una respuesta bastante arrogante y pomposa que podría imaginar a algunas personas dando una respuesta con ese tono.

Obviamente era un programador alfabetizado al estilo de Knuth. Para un discípulo de LP, el código debe ser autodocumentado para ser válido. Entonces la única respuesta posible es "sí".

El problema aquí es que no hay muchos lenguajes de programación alfabetizados y ninguno que yo conozca en el uso comercial generalizado. Por lo tanto, tendría que ser una posición de nicho en alguna parte.

Creo que lo que el entrevistador podría haber estado buscando es: "¿Cómo se escribe el código de autodocumentación?" con un implícito "¿Cuál es su actitud hacia la documentación?"

Fui a una conferencia realmente inspiradora de un tipo llamado Robert C Martin una vez donde habló sobre el capítulo de 'métodos de escritura' de su libro Clean Code.

Obviamente estaba presentando un poco la posición de un purista, pero tomé en cuenta su consejo de que cuando cortas tu código en pequeños métodos reutilizables y usas trucos simples como:

• Mantener todas las declaraciones dentro de un método al mismo nivel de abstracción
• Extrayendo el contenido de la condición de flujo de control o bloques de bucle en llamadas a métodos
• Cuando te encuentras pasando los mismos parámetros a varios métodos en una clase, separando una nueva clase
• Y trucos simples como reemplazar expresiones crónicas booleanas con llamadas a métodos
• etc ...

Terminas con un código legible y algo autodocumentado (siempre que pongas esfuerzo en nombres concisos pero descriptivos) que sea más fácil de entender y mantener.

He encontrado que esto es realmente útil, pero requiere un conocimiento de los patrones de diseño para que funcione bien y definitivamente necesitas complementar el enfoque con documentación de clase y de métodos de alto nivel.

Por lo general, el código autodocumentado se refiere a la práctica de usar una convención de nomenclatura para variables, funciones, etc., de modo que el propósito del código sea evidente por sí mismo. Por lo tanto, ningún código por sí solo no se auto documenta. No entiendo a qué te refieres en el tercer párrafo. Eso parece no tener nada que ver con el código autodocumentado.

Jack Reeves hizo un argumento convincente de que el código es diseño . En lo que respecta a muchos, el código real es el único "documento" que le dice qué hace el sistema. Todo lo demás decae a medida que un sistema en vivo tiende a desviarse más y más del sistema diseñado. Incluso si tuviera que generar un documento a partir del código (como muchas herramientas UML pueden hacer hoy en día), todavía es solo una documentación precisa del sistema en ese momento .

Entonces sí, el código es autodocumentado. Lo bien que está documentado es otra pregunta completa.

A medida que adquirí más experiencia, aprendí que la respuesta real es que el código más el entorno del lector determina el nivel de autodocumentación.

Para minimizar la variación entre el entorno del lector y el entorno del escritor, agregamos comentarios. Cuantos más comentarios se necesiten, generalmente menos experimentado será el escritor. Hay un ensayo maravilloso que describe este aspecto del desarrollo de software, pero no recuerdo quién lo escribió o dónde lo encontré.

Sé que la respuesta que la mayoría de la gente espera a esa pregunta sería "no", pero voy a decir que sí. Si me pidieran esto en una entrevista para un trabajo, todavía diría que sí.

He trabajado en muchos proyectos diferentes con código abierto y cerrado. Han variado en documentación desde simples comentarios que se dejan como notas del programador hasta documentaciones completas de API. Si bien la documentación de la API puede ser excelente, siempre llegué a una situación en la que la documentación en lenguaje escrito era insuficiente para determinar el comportamiento real del código. Terminé mirando el código fuente, aplicando ingeniería inversa a las aplicaciones o molestando a los desarrolladores con acceso a la fuente para ver el código fuente y especificar más.

Para mí, el código es la documentación definitiva. No importa cuánto escriba en palabras lo que va a hacer un programa, el código define el comportamiento exacto.

Estoy de acuerdo en que al escribir el código debe intentar que su código sea lo más autodescriptivo posible. Sin embargo, como otros han mencionado, es casi imposible en un programa complejo describir completamente todo lo que está haciendo el código. No estoy en contra de los comentarios, de hecho, encuentro que con buenos comentarios puede ser más fácil leer el código, a pesar de que el código podría explicarse sin que los comentarios lean inglés o algún idioma hablado es casi siempre más fácil.

He descubierto que la documentación más útil casi nunca es comentarios. La mayoría de los proyectos en los que he estado trabajando recientemente incluyen wiki que incluyen todas las diferentes partes, cómo se conectan. Intento explicar lo que tenía en mente cuando estaba escribiendo el código para que otras personas no lo rompieran porque no entendían por qué. También puede ayudar a otra persona a refactorizar el código con más confianza. A menudo me siento reacio a refactorizar el código porque nunca sé qué podría romper y no hay explicación. Incluso si eres la única persona que trabaja en un proyecto que te garantizo en un año o dos, olvidarás por qué hiciste algo, incluso si es el código más hermoso, aún puedes olvidar por qué está ahí.

Claro, si tienes tiempo ilimitado. He pasado más de 25 años documentando código para otros desarrolladores. Mi posición siempre ha sido que trato de explicar algo para que otro desarrollador pueda asimilarlo en 5 minutos, cuando simplemente podrían examinar el código y resolverlo en media hora. Si salvo a todos los que miran ese método 25 minutos, entonces he hecho mi trabajo.

Creo que el diagrama de clase siempre debe usarse para documentar el código. No creo que si miras el código directamente puedes ver la arquitectura completa. Estoy de acuerdo en que si ha escrito el código usted mismo o ha estado trabajando en él durante mucho tiempo, entonces puede entenderlo, pero cada vez que surge una nueva demanda, cada vez que necesita mirar el código y buscar dónde agregar este nuevo código.

Lo que hacemos en nuestra empresa es tener vistas de diagramas de clases de nuestro proyecto. Realmente no pasamos tiempo modelando, solo usamos el diagrama de clase para visualizar el código después de una ingeniería inversa. Si el código cambia, entonces hay un mecanismo de fusión y mis diagramas de clase siempre se actualizan.

Lo fantástico es poder agregar comentarios, restricciones en el diagrama además de java doc. Revertimos el proyecto, luego creamos un modelo y finalmente extraemos vistas del modelo que se muestra como diagramas de clase UML. No codifico en esta etapa, pero obtengo una copia azul de la arquitectura de código y trabajo para crear o ampliar mi arquitectura actual. Si me gusta, presiono un botón y mi código existente se fusiona con mis diagramas. Me refiero a fusionar y ciertamente no a la generación de código completo. Solo se escribe el delta entre el código existente y mis diagramas, no el código completo cada vez.

He estado estudiando durante muchos años, tengo una maestría y sigo codificando, pero no quiero ser solo un escritor de Java y me gustaría usar mi cerebro un poco más. Las vistas UML me dan lo que necesito para pensar en mi arquitectura, comunicarme con los otros miembros del equipo y crear una mejor arquitectura sin usar el desarrollo Model Driven, sino solo el delta entre el código escrito manualmente existente y crear gráficamente diagramas de clase. Creo mi arquitectura a nivel de código, luego la invierto y miro el modelo. Creo vistas e intento mejorar mi arquitectura directamente en el código, luego retrocedo y veo lo que se hace, etc. Es una iteración permanente sin generación de código impulsada por el modelo, pero sincronización en vivo o fusión entre código y UML. Lo que me gusta es que el código impulsa el UML y ciertamente no es lo contrario.