Documentación de código primero? [cerrado]

¿Alguien ha intentado crear una documentación de código completa primero, antes de escribir el código? Estaba pensando en esto antes porque pensé que ayudaría a escribir una interfaz concreta y me aseguraría de que su diseño inicial no se basara al hacerle pensar en cómo interactúan las clases. ¿Es esta una buena idea? ¿Alguien lo ha intentado? Ana

Si.

Te hace pensar en qué, exactamente, se supone que debe hacer tu código . La idea es que podría comenzar con cualquier parte del código y saber exactamente lo que debe hacerse para completar ese módulo.

También es más fácil arreglar algo en el tablero de dibujo que en el IDE.

Hay dos formas de pensarlo:

1) Documentación como en documentos de Word, Wiki, etc. Por definición, no puede tener una documentación de código completa porque no tiene un código para documentar. Puede intentar documentar el diseño de alto nivel, suposiciones, interfaces y contratos primero.

2) Documentación como pruebas ejecutables. Hay una escuela de pensamiento que establece que las pruebas unitarias ejecutables son la mejor documentación. Esta escuela de pensamiento también aboga por este tipo de documentación antes de escribir el código (TDD). Al mismo tiempo, no escribe todas las pruebas para todo el sistema desde el inicio. Primero lo desglosa por casos de uso, luego realiza pruebas y codifica por caso de uso.

Comenzar con la documentación es un modelo de cascada clásico, y tiene todas las trampas asociadas con ese modelo. En términos generales, cuanto más documente, más tendrá que actualizar cuando cambien los requisitos. Una ventaja de comenzar con la documentación del usuario es que puede recibir comentarios (y, por lo tanto, cambios) antes. Pero la experiencia muestra que la mayoría de las personas son malas para mapear mentalmente la documentación con las acciones. Por lo tanto, utilizamos prototipos, que permiten a las personas usar el software y dar su opinión de esa manera.

Una variación de "documentación primero" es la programación alfabetizada . Comience escribiendo una descripción de lo que hará el programa desde la perspectiva de los programadores. Sigue ajustando eso hasta que se compile. Voila, un programa alfabetizado.

Personalmente, creo que es mejor usar diagramas (como UML) para hacer modelos simples para mostrar el flujo de las cosas. Esto es mucho más rápido que documentar las cosas en palabras y, si se hace bien, puede ser igual de descriptivo. Sin embargo, dudaría en hacer la documentación completa porque personalmente nunca he tenido un proyecto en el que he trabajado que no haya cambiado en el transcurso de la programación.

EDITAR: aunque se debe hacer algo de documentación a medida que avanza mucho. Esto hace que sea más fácil hacer la documentación completa más adelante.

Joshua Bloch analiza este mismo punto en su entrevista para el libro "Codificadores en el trabajo".

Contrariamente a los puntos de vista más ortodoxos y académicos, él aconseja algo acorde con sus pensamientos (¿tal vez lo haya leído allí usted mismo?): Antes de escribir la documentación, debe comprender qué es lo que quiere del sistema y obtener una visión más "real" "sentimiento. Para este propósito, diseñaría parte de las interfaces y un código de cliente que las usa.

Lo más importante es saber qué está tratando de construir: qué problema está tratando de resolver. La importancia del análisis de requisitos no puede ser exagerada. Hay personas que piensan: “Oh, sí, análisis de requisitos; vas a tu cliente y le dices: "¿Qué necesitas?" Él te lo dice y ya terminaste.

Nada mas lejos de la verdad. No solo es una negociación sino que es un proceso de comprensión. Muchos clientes no le dirán un problema; Te dirán una solución. Un cliente podría decir, por ejemplo, “Necesito que agregue soporte para los siguientes 17 atributos a este sistema. Entonces tienes que preguntar, '¿Por qué? ¿Qué vas a hacer con el sistema? ¿Cómo esperas que evolucione? '”Y así sucesivamente. Usted va y viene hasta que descubre lo que todo el cliente realmente necesita que haga el software. Estos son los casos de uso.

Encontrar un buen conjunto de casos de uso es lo más importante que puede hacer en esta etapa. Una vez que tenga eso, tiene un punto de referencia contra el cual puede medir cualquier solución posible. Está bien si pasas mucho tiempo consiguiendo que esté razonablemente cerca de lo correcto, porque si te equivocas, ya estás muerto. El resto del proceso será un ejercicio inútil.

Lo peor que puede hacer, y he visto que esto suceda, es que consiga a un grupo de tipos inteligentes en una habitación para trabajar durante seis meses y escriba una especificación de sistema de 247 páginas antes de que realmente entiendan qué es. tratando de construir Porque después de seis meses, tendrán un sistema especificado con mucha precisión que bien puede ser inútil. Y a menudo dicen: "Hemos invertido tanto en la especificación que tenemos que construirlo". Entonces construyen el sistema inútil y nunca se usa. Y eso es horrible. Si no tiene casos de uso, construye la cosa y luego trata de hacer algo muy simple y se da cuenta de que, "Dios mío, hacer algo muy simple como tomar un documento XML e imprimirlo requiere páginas sobre páginas de repeticiones. código." Y eso es algo horrible.

- Joshua Bloch, de una entrevista en " Codificadores en el trabajo: reflexiones sobre el arte de la programación " por Peter Seibel

Si ya está pensando en este sentido, sería bueno que pueda obtener el libro y leer toda la entrevista. Como dije, él siempre es muy esclarecedor.

Algunas personas incluso van más allá y afirman que una empresa debería trabajar completamente al revés, por lo que

1. Escribe el comunicado de prensa
2. Escribe una pregunta frecuente
3. Definir la experiencia del cliente.
4. Escribe el manual del usuario
5. Comience a programar

Ver http://www.allthingsdistributed.com/2006/11/working_backwards.html

Escribir la documentación completa del código primero es probablemente exagerado y recuerda un poco a la metodología de cascada. Sin embargo, he descubierto que un enfoque más pragmático es escribir el README primero. Este es el por qué:

El archivo README no documenta cada detalle de su proyecto. En cambio, generalmente contiene la siguiente información:

1. Descripción : breve "argumento de venta". Dígale al lector por qué deberían seguir leyendo.
2. Ejemplos rápidos : fragmentos de código cortos o capturas de pantalla para admitir la descripción.
3. Inicio rápido : cómo comenzar , instrucciones de instalación y más ejemplos.
4. Documentación adicional : enlaces a los documentos completos y más información.
5. Organización del proyecto : quiénes son los autores, cómo contribuir, cómo presentar errores.
6. Avisos legales : licencia, derechos de autor y cualquier otro detalle legal.

Escribir el "argumento de venta" por adelantado me obliga a ser muy claro sobre por qué debería existir este proyecto y por qué los desarrolladores deberían usarlo. El simple acto de escribir oraciones completas para describir el proyecto a menudo lo cambia para mejor: lo comprende mejor, desarrolla nuevas ideas y descubre posibles problemas. También es una gran herramienta de priorización: ¡cualquier cosa en el "argumento de venta" es imprescindible!

Los "ejemplos rápidos" y la "guía de inicio rápido" me obligan a pensar en los casos de uso clave desde la perspectiva del usuario. Descubrí que hacer esto antes de escribir cualquier código, antes de estar empantanado en detalles de implementación y plazos ajustados, conduce a API y diseños mucho más limpios. Recuerde: los programas deben estar escritos para que la gente los lea, y solo de forma incidental para que las máquinas los ejecuten ( SICP ).

En "documentación adicional", creo un resumen de las piezas que necesitarán documentación detallada, que se realizará más adelante. La "organización del proyecto" me permite descubrir quién trabajará en el proyecto y las prácticas de codificación. "Avisos legales" ... bueno, también podría eliminarlos.

Una vez que tenga este README básico en su lugar, tendrá un documento útil para discusión, revisiones de diseño, división del trabajo y planificación del proyecto. A medida que trabaje en el proyecto, consulte con frecuencia el archivo README para asegurarse de que todavía está en camino. Además, la actualización incremental de README y la "documentación adicional" a medida que avanza significa que toda su documentación se realizará cuando se realice el código, lo cual es una experiencia mucho más agradable que tener que apresurarse a documentar todo en el último momento.

Para obtener más información, consulte lo siguiente:

1. Desarrollo dirigido por el archivo Léame
2. El código más importante no es el código.
3. Eres lo que documentas

¿Por qué no querrías pensar en cómo interactúan las clases? Por qué es eso algo malo? De hecho, pienso en las interacciones incluso antes de saber cuáles son las clases. De esa manera las clases se identifican.

Debe tener alguna idea de lo que planea hacer antes de escribir el código. El problema siempre es cómo mantener sincronizado lo que ha codificado con lo que ha escrito. Algunos dicen que no intentes, otros dicen que olviden los documentos iniciales y sigan con los comentarios. Por supuesto, el código es siempre la fuente canónica. El problema es si vale la pena documentar lo que hace el código para quienes vienen más tarde o lo usan. Cualquiera puede descubrir qué hace una función. El trabajo del escritor es ayudar a alguien a comprender en 5 minutos lo que cualquiera puede resolver en una hora. Sume los deltas y determine su ruta.