Documentación del código fuente externo hipervinculado [cerrado]

¿Por qué aún incorporamos descripciones en lenguaje natural del código fuente (es decir, la razón por la que se escribió una línea de código) dentro del código fuente, en lugar de hacerlo como un documento separado?

Dada la gran cantidad de bienes raíces que se brindan a los entornos de desarrollo modernos (monitores de alta resolución, monitores duales, etc.), un IDE podría proporcionar paneles semi-bloqueados en los que el código fuente se separa visualmente de, pero está intrínsecamente vinculado a sus comentarios correspondientes Por ejemplo, los desarrolladores podrían escribir comentarios sobre el código fuente en un lenguaje de marcado hipervinculado (vinculando a requisitos de software adicionales), lo que simultáneamente evitaría que la documentación saturara el código fuente.

¿Qué deficiencias inhibirían tal mecanismo de desarrollo de software?

Una maqueta para ayudar a aclarar la pregunta:

Cuando el cursor está en una línea particular en el código fuente (se muestra con un fondo azul, arriba), la documentación que corresponde a la línea en el cursor se resalta (es decir, se distingue de los otros detalles). Como se señaló en la pregunta, la documentación permanecería sincronizada con el código fuente a medida que el cursor salta a través del código fuente. Una tecla de acceso rápido podría cambiar entre "modo de documentación" y "modo de desarrollo".

Las ventajas potenciales incluyen:

• Más código fuente y más documentación en la (s) pantalla (s) a la vez
• Posibilidad de editar documentación independientemente del código fuente (¿independientemente del idioma?)
• Escriba documentación y código fuente en paralelo sin conflictos de fusión
• Documentación hipervinculada en tiempo real con formato de texto superior
• Traducción automática casi en tiempo real a diferentes idiomas naturales
• Cada línea de código se puede vincular claramente a una tarea, requisito comercial, etc.
• La documentación podría marcar la hora automáticamente cuando se escribió cada línea de código (métrica)
• Inclusión dinámica de diagramas de arquitectura, imágenes para explicar relaciones, etc.
• Documentación de fuente única (p. Ej., Fragmentos de código de etiqueta para la inclusión del manual del usuario).

Nota:

• La ventana de documentación se puede contraer
• El flujo de trabajo para ver o comparar archivos de origen no se vería afectado
• Cómo ocurre la implementación es un detalle; la documentación podría ser:
  • guardado al final del archivo fuente;
  • dividido en dos archivos por convención ( filename.c, filename.c.doc); o
  • totalmente basado en bases de datos
• Por documentación hipervinculada, me refiero a vincular a fuentes externas (como StackOverflow o Wikipedia) y documentos internos (es decir, un wiki en un subdominio que podría hacer referencia cruzada a la documentación de requisitos comerciales) y otros archivos fuente (similares a JavaDocs).

Tema relacionado: ¿Qué pasa con la aversión a la documentación en la industria?

Este problema me molesta todo el tiempo, y acabo de tener una idea sobre la dirección en la que deberíamos tratar de resolverlo (así es como encontré esta pregunta).

Creo que el problema de la documentación vinculada se pensó mal cuando decidimos incluir la documentación del usuario en el código fuente. Como lo hace docco.

En primer lugar, permite diferenciar los comentarios de código de la documentación del usuario.

Los comentarios de código normalmente son mejores cuando son cortos, de hecho súper cortos, por lo que puedo leer el código que hace las cosas sin tener que ver un poco de poesía de por qué y cómo funciona.

Los comentarios de los usuarios están destinados a las personas que intentan usar su biblioteca / API, y pueden incluir ejemplos de uso, explicaciones de por qué se implementó de esa manera o instrucciones sobre cómo extender la biblioteca. Este tipo de comentarios tienden a ser muy detallados.

Estoy de acuerdo con el hecho de que la documentación debe escribirse en texto sin formato, por lo que no es un proveedor fijo y es fácil de agregar en un VCS. Pero creo que mantener la documentación del usuario en el archivo fuente fue un gran error por al menos dos razones:

• Código más difícil de leer
• Documentación no lo suficientemente flexible (supongamos que necesito dos páginas de documentación que utilicen el mismo código de ejemplo o que tengan una página de documentación que necesite intercalar código de dos archivos de origen diferentes).

Entonces, ¿por qué queremos tenerlo en el mismo archivo? Bueno, nadie quiere que sus documentaciones no estén sincronizadas con el código. Pero lo hacemos de todos modos, y especialmente hoy en día con el gran éxito de Markdown. Lo cual creo que está en el camino correcto, pero si se queda corto, muy corto.

Cuando intercalamos el comentario del código con el comentario del usuario, tenemos un enlace bidireccional. Eso nos permite ver fácilmente qué comentario corresponde a qué parte del código. También podemos ver si algún código no está documentado. Lo que no ofrece es una forma de ver si el comentario se actualiza o no, y eso sucede mucho cuando su código es difícil de leer (porque la documentación lo hizo feo).

¿Qué pasa si en lugar de tener un enlace de 2 vías, tenemos una? Documentación que apunta al código. Podríamos tener un código de descuento con comandos especiales como:

Some documentation right here that explains the following code:
   @include_file <path/to/some/file>:<line_start>-<line_end>
or
   @include_file <path/to/some/file>
     @starts_with "some regexp or literal text to search"
     @ends_with "another regexp"
or
   @include_file <path/to/some/file>
     @class MyClass
     @method foo
or any combination or way of linking you could imagine

We can even have semantic in the directives:
   @explain_code <path/and/same/of/above>
   @example_code <path/and/same/of/above>
   @performance_notice <path/and/same/of/above>

Which would do basically the same, but it adds the intention of why
do we want to add this code in the first place, which could be 
used different by an IDE. 

Esto tiene el beneficio de ser marcado con algunas adiciones, y con las herramientas adecuadas, podríamos agregarle más valor.

Imagine este enlace unidireccional con herramientas como gruñido (incluso con la tarea de observación). Puede detectar cuándo cambia un archivo fuente, ver qué archivos de documentación dependían de él y advertir al usuario (o marcarlo en alguna parte) si el código que se comentó había cambiado.

404 Pagina no encontrada

Al trabajar con código, no desea que sus comentarios se pierdan y eso es lo que sucederá cuando separe el código y los comentarios en documentos separados.

Además, mantener el control de versiones entre su documento de comentarios y el documento de código causará más dolor que ganancia.

Algunas de las sugerencias que hace me gustan mucho, pero podrían implementarse fácilmente al mismo tiempo que tienen código y comentarios en 1 archivo.

Posibles desventajas que veo:

• Necesita un editor especial que implemente esta función

• El código ya no es solo texto simple, es fácil de manipular y comprometerse con VCS-es

• Necesita dos veces más ancho de pantalla para trabajar con el código

En cuanto a sus argumentos:

Más código fuente y más documentación en la (s) pantalla (s) a la vez

Pero puede ser un inconveniente si desea ver dos archivos uno al lado del otro.

Posibilidad de editar documentación independientemente del código fuente (¿independientemente del idioma?)

Yo diría que en realidad es una desventaja. Personalmente trato de mantener la documentación lo más cerca posible del código, para que no quede desactualizada.

Escriba documentación y código fuente en paralelo sin conflictos de fusión

De nuevo, posiblemente una desventaja. Si sus documentos están profundamente entrelazados con el código, ¿cómo puede editarlos de forma independiente?

Documentación hipervinculada en tiempo real con formato de texto superior

Si está en el código, ya está en tiempo real;) En cuanto a los hipervínculos, el salto a la definición ya está implementado en la mayoría de los IDE.

Traducción automática casi en tiempo real a diferentes idiomas naturales

No veo por qué no puedes hacer eso con comentarios regulares / docstrings.

Cada línea de código se puede vincular claramente a una tarea, requisito comercial, etc.

Sobre esto no estoy seguro ... ¿No se puede lograr con comentarios regulares?

La documentación podría marcar la hora automáticamente cuando se escribió cada línea de código (métrica)

¿VCS-es no proporciona este tipo de información ya?

Dicho esto, me gusta bastante el diseño en sí, pero no veo la necesidad de cambiar el formato del archivo, no es tan difícil generarlo a partir de comentarios regulares. Hay un montón de generadores de documentación que hacen eso, por ejemplo, Docco y sus sucesores, como Pycco o Marginalia .

En primer lugar, los comentarios del documento deben ir con el código; moverlos a otro lugar solo hace que las cosas sean increíblemente difíciles de manejar para obtener prácticamente cero ganancias. ¡Entonces, para qué molestarse!

Sin embargo, lo que se podría hacer es tomar esos comentarios incrustados y ocultarlos en el editor, mostrándolos en una burbuja o información sobre herramientas o lo que sea necesario. Espero que este enfoque pueda alentar a las personas a escribir mucha más documentación en el código; por ejemplo, una descripción de una clase podría ir con la clase en lugar de en un documento de diseño externo.

Actualmente puede incrustar hipervínculos en comentarios de código, y puede generar documentos a partir del código utilizando herramientas como Doxygen o Sphinx. Supongo que solo se necesitaría una extensión elegante en el editor de código para admitir mejor estas herramientas.

No vincularía ninguna línea de código a un rastreador de errores o herramienta de requisitos, ese es un mejor trabajo para su SCM. Luego puede ver las ediciones de código por confirmación que están vinculadas a una tarea. Tampoco integraría la documentación almacenada en el código contra el rastreador de errores: estaría jodido si alguna vez quisiera migrar a uno nuevo (hmm, puedo ver que esta característica se agrega a TFS en este momento) o si usted perdió su historial de confirmaciones (lo que sucede)

Además de lo que ya dice @Bogdan, agregaría algunos:

• Configuré mi IDE para tener siempre 2 archivos a la vez. Con la función que sugiere, básicamente necesitaría 2 monitores para ver la misma cantidad de información y 3 para hacer lo que estoy haciendo ahora con 2.
• Mientras navega por un archivo, no ve de inmediato los comentarios, y si no sabe exactamente lo que está buscando, es muy difícil encontrarlo.
• Mientras busco en un archivo, no puedo buscar en los comentarios directamente (o tan fácilmente).
• A veces necesito hacer varias pruebas / escribir fragmentos cortos de código en el servidor en vivo, a través de ssh . Aunque la funcionalidad que está diciendo podría integrarse con VIM u otros editores de línea de comandos, lo más probable es que haya problemas bastante grandes

• La mayoría de los IDE admiten el colapso de código / comentarios , y los resultados finales son los siguientes:

  En lugar de lo normal:

  

Haga que el código sea más legible, en caso de que no necesite los comentarios.

Código fuente y documentación de la forma en que debe hacerse.

http://jasmine.github.io/2.3/introduction.html