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

11

¿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

documentation

— ana
fuente

2

Si. Es una buena idea. La gente lo hace todo el tiempo. ¿Que más quieres saber?

— S.Lott

99

Esta es una pregunta subjetiva. Alguien lo ha hecho al menos algunas veces, por lo que la respuesta será afirmativa. Personalmente prefiero simplemente saltar y hacer un prototipo primero, ya que inevitablemente redescubriré un mejor diseño unas 5 veces en el proceso. Al abordar algo complejo, primero rasco algo en un papel. Si es trivial, entonces tiendo a saltar directamente. StyleCop me ayuda a llenar los vacíos más tarde.

— Trabajo

2

Es una gran idea, de lo contrario terminas con características indocumentadas.

— Chris

8

@ S.Lott el simple hecho de que está haciendo la pregunta implica que está buscando más información, ya que estoy bastante seguro de que estaba al tanto. Pero parece que prefiere hacer comentarios sarcásticos sobre las fallas de otras personas.

— Kenneth

2

Sería aún mejor si escribiera pruebas de aceptación y luego utilizara TDD para cumplir con esas pruebas de aceptación;).

— Martin Blore

5

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.

— Maxpm
fuente

12

Más fácil de arreglar, sí. Más fácil de notar, rara vez. Los diseños casi siempre se ven bien hasta que intentas implementarlos.

— CaffGeek

@Chad Eso es cierto. He editado mi respuesta para reflejar eso.

— Maxpm

44

Estoy en desacuerdo. Crear la documentación completa primero es mucho peor que la documentación suficiente para saber a dónde ir después. El cambio sucede. No hay forma de saber si vas en la dirección correcta, y cuando lo descubres, ya estás muy retrasado. Vaya con lo que funciona, mejore y corríjalo a medida que avanza, deje que el código sea la documentación más actualizada.

— Zachary Scott

44

Por supuesto, tan pronto como cambie su código para corregir un error o para cumplir con un nuevo requisito, su documentación está desactualizada. ¡La documentación como pruebas ejecutables es el camino a seguir!

— Johnsyweb

Dibuje (bosquejo / bosquejo) ideas de antemano sí, pero no cree documentación. A menos que prefiera desperdiciar mucho esfuerzo porque estará desperdiciando gran parte del esfuerzo inicial ya que el diseño se pone en práctica. Además, solo las clases / métodos públicos o internos deben estar completamente documentados (incluida la descripción completa y los parámetros). Las cosas locales privadas deben tener frases que describan lo que hacen para referencia futura, pero cualquier otra cosa es un desperdicio porque inevitablemente se omitirán durante la fase de generación de documentación de todos modos.

— Evan Plaice

10

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.

— Yuriy Zubarev
fuente

2

+1 para TDD. Absolutamente una mejor opción que documentar, luego tener que cambiar cantidades significativas de documentación si el código cambia.

— Ethel Evans

También +1 para documentación en forma de TDD.

— sevenseacat

PUEDE tener la documentación completa del producto antes de que el producto exista. Lo hice, trabajé en proyectos donde era un requisito. No tendrá capturas de pantalla, pero puede tener todo lo demás (incluidos los diagramas de Visio que representan la ubicación de los elementos en la pantalla).

— Jwent

@jwenting también tengo y era una colección de diagramas, así como más de 200 páginas de documentos de Word. No solo fue una completa pérdida de tiempo, sino que requirió 2 meses para producir y una cantidad significativa de tiempo de nuestros PM para actualizarse constantemente a medida que el diseño evolucionaba hacia el producto final. En realidad, probablemente habría ido mucho más rápido con maquetas gráficas usando Balsalmiq. La próxima vez que trabaje en un proyecto en el que esto sea un requisito, voy a señalar que se debe asignar a otra persona para que lo administre a tiempo completo porque ese es el esfuerzo que requiere mantener.

— Evan Plaice

+1 TDD para pruebas básicas de componentes individuales y diagramas para suposiciones generales de diseño (énfasis en la suposición porque el diseño real debe escribirse como la mejor aplicación práctica no como una implementación 1-1 del diagrama, se llaman suposiciones por una razón ) La documentación completa del software de todas las clases / métodos / propiedades públicas / internas viene en último lugar a través de un generador de documentación (todas las propiedades / devoluciones / comentarios deben completarse primero) y todas las cosas privadas / locales obtienen frases para describir lo que hacen para referencia futura (privado / local es ignorado por el generador).

— Evan Plaice

7

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.

¡Exactamente! El cambio sucede. La documentación se pudre. El código es la forma más verdadera de documentación.

— Zachary Scott

3

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.

— Kenneth
fuente

3

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.

— DPM
fuente

Este es un buen consejo, pero una buena documentación incluye el uso de la API.

— Frank Hileman

Para el registro, aunque aprecio la edición, creo que esa cita podría no haber sido la que estaba pensando. Parece tangencialmente relacionado y de más alto nivel o relacionado con la fase de requisitos. Creo que dijo que antes de escribir la documentación comenzaría a codificar, escribir el código del cliente que usaría la interfaz para tener una idea aproximada de la interfaz correcta y que (esta es la parte contraria intuitiva en mi opinión) que debería venir primero, antes de escribir cualquier documento de diseño de bajo nivel. Por supuesto, es mi culpa por no haber encontrado la cita cuando escribí esta respuesta.

— DPM

1

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

Escribe el comunicado de prensa
Escribe una pregunta frecuente
Definir la experiencia del cliente.
Escribe el manual del usuario
Comience a programar

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

— asmaier
fuente

1

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:

Descripción : breve "argumento de venta". Dígale al lector por qué deberían seguir leyendo.
Ejemplos rápidos : fragmentos de código cortos o capturas de pantalla para admitir la descripción.
Inicio rápido : cómo comenzar , instrucciones de instalación y más ejemplos.
Documentación adicional : enlaces a los documentos completos y más información.
Organización del proyecto : quiénes son los autores, cómo contribuir, cómo presentar errores.
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:

— Yevgeniy Brikman
fuente

0

¿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.

— Remojar
fuente

0

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.

— SnoopDougieDoug
fuente