Ingeniería de software: ¿Cómo documentan los programadores su trabajo?

Código

• Nombres de variables, nombres de métodos, nombres de clases
• Verificar comentarios
• Comentarios en el código cuando corresponda
• Prueba de nomenclatura cuando pruebas unitarias

Si se hace adecuadamente, debería ser suficiente para que otro desarrollador recoja el código.

Los wikis y los generadores de documentos son útiles cuando está desarrollando bibliotecas complejas / grandes o sistemas de back-end que serán consumidos por otros desarrolladores pero que conllevan un costo de mantenimiento. Solo documenta sus interfaces públicas en estos casos.

Documentación formal

Dependiendo del proyecto, es posible que necesite producir documentación formal como arquitectura, diseño funcional, diseño técnico y documentos API. Estos documentos generalmente se producen en una herramienta adecuada para el trabajo y si es una empresa establecida, probablemente tendrá algunas plantillas o el cliente le dará algunas plantillas.

Además, si tiene que cumplir con estándares como ISO 9000, es posible que deba presentar documentación formal adicional según lo dicte el estándar.

Documentación del cliente

Las guías de usuario, manuales, tutoriales, videos, etc. son producidos idealmente por un escritor técnico. Si no hay un escritor técnico, esto puede ser responsabilidad de los programadores. Este tipo de documentación puede tomar muchas formas. Puede producir recorridos de escenarios que fluyan muy bien a partir de la historia o el desarrollo de casos de uso si está desarrollando de esa manera. Puede producir un manual que detalle cada pantalla. Puedes producir una wiki.

Conclusión

El tipo de documentación producida depende en gran medida de los requisitos de los clientes, el cumplimiento de las normas y la política de la empresa. En mi experiencia, los desarrolladores prefieren no documentar nada, sino que producen código de autodocumentación de calidad.

Cuatro formas principalmente:

1. Mediante el uso de funciones de documentación compatibles que permiten la generación de documentación; por ejemplo, cadenas de documentos en Python o clase /// html y comentarios de métodos en C #.
2. Comentarios en el código que proporcionan contexto o explicación para secciones de código; estos pueden ser comentarios en línea o en línea separada.
3. Con documentos de diseño, generalmente escritos en Microsoft Word, donde puedo describir un desafío de diseño, describir soluciones a él, evaluar las soluciones, explicar las razones para elegir una solución específica y luego especificar la solución elegida con mayor detalle.
4. Con una presentación de diapositivas, generalmente realizada con Microsoft PowerPoint, para “simular” varias partes de la interfaz de usuario, o para describir un desafío de la interfaz de usuario y varias posibles soluciones.

También puedo usar diagramas UML para describir estructuras de datos, transiciones de estado o interacciones de componentes.

Puede que me encuentre en una situación única porque trabajo en un modelo de agencia.

Documento todo el sistema que planeo construir antes de comenzar a escribir código. Diagramas de relaciones entre entidades, interfaces, estructuras de bases de datos, API externas, etc. Hago esto porque es posible que no sea yo quien escriba el código para todo el proyecto, y necesito asegurarme de que todas las partes funcionen juntas cuando esté hecho.

Luego, mientras escribo el código, nombro variables y clases de manera detallada para que su propósito sea obvio, y dejo comentarios para cualquier cosa que creo que puede no ser obvia. Por ejemplo, si tengo que hacer una combinación de cadenas, lo hago a través de varias líneas con comentarios, o lo haré todo en una línea con un comentario de varias líneas que describa qué y por qué lo hice.

Cuando termine, actualizo mi documentación original para abordar los cambios realizados durante la compilación y para agregar documentación adicional sobre las áreas problemáticas que preveo.

Hago esto porque tengo un equipo de mantenimiento que tendrá que ocuparse del código más adelante. Tengo 50 proyectos antiguos en esta compañía que regresan regularmente para cambios y actualizaciones, y si no quiero que el equipo de mantenimiento me interrumpa 15 veces al día para preguntar por qué hice algo en particular hace 2 años, yo tienen que asegurarse de tener la documentación que necesitan para resolverlo por su cuenta.

¡Bueno, un número inquietante de ellos no documenta las cosas!

Pero cuando lo hacen, hay una variedad de formas. Lo que pasa por la documentación típica es a menudo cosas como comentarios en código, comentarios de confirmación de git y otras cosas como esta que son parte o están asociadas con el código.

Esto, por supuesto, no está completo.

Hay un par de niveles de documentación:

1. ¿Cómo está organizado el sistema, qué piezas hay y cómo se comunican, comienzan, configuran, registran datos, almacenan datos, etc.?
2. ¿Cómo se organiza este componente particular del sistema? ¿Qué son las entradas y salidas?
3. ¿Cómo funciona esta rutina? ¿Hay algo complicado aquí? ¿Qué cambié en esta última confirmación? ¿Para qué boleto es este cambio?

La “documentación típica” cubre el nivel 3. A menudo, los otros dos niveles no están cubiertos, o si lo están, son diapositivas de PowerPoint obsoletas.

Francamente, este campo no se tomará en serio como un campo de ingeniería hasta que tengamos la documentación correcta.

La documentación más importante que puede hacer un programador es documentar la API pública de un programa y, tratando el software como un sistema cerrado, documentar todos los datos de puntos que pueden ingresar al sistema y todos los datos de puntos pueden salir. Esta documentación debe incluir todas las estructuras de datos dentro y fuera. Si hay opciones, debe ser una lista exhaustiva de esas opciones. Incluya todos los casos extremos si los conoce. Esta documentación se utiliza para construir las pruebas.

Lo que es menos importante es documentar los trabajos de salchichas internas de las partes privadas de la API. Comente solo cuando pueda haber confusión. La mayoría de los programadores simplemente leerán el código para ver qué está haciendo de todos modos.

La mayoría de los lenguajes de programación tienen su propia metodología de documentación, como perldoc, pydoc, javadoc.

Honestamente, Doxygen es invaluable para esto porque tomará ciertos comentarios (dependiendo de su formato) y generará documentación. Lo uso para generar documentación a partir de comentarios que describen variables miembro, definiciones de funciones, etc. (cosas que creo que son importantes para que alguien sepa si van a ver la documentación e intentar obtener la esencia de lo que hace mi código) en código C ++ . También se puede usar con C #. Lo mejor es que incluso puede incluir partes adicionales de su documentación (como introducciones, descripciones de alto nivel) como comentarios de código e incluirá aquellos en la documentación generada. Lo mejor es que solo tiene que escribir una vez comentando su código (lo que debería hacer de todos modos). Usar esto junto con el control de versiones y un buen sistema de seguimiento de errores que puede generar informes sobre defectos abiertos y cerrados es una buena forma de documentar el trabajo.

Fácil. Solo piense en el pobre tonto que tiene que mantener o escribir sobre su código. Ponte en sus zapatos.

Yah, puedes revertir una subcadena estúpida en una línea. Bien por usted. Lo entendemos.

Pero no hagas eso.

Por qué: otras personas tendrán que analizar su código bee-YOOT-iff-all, mucho, mucho después de que haya alimentado su Ego con una línea. Y esa es una cantidad de trabajo totalmente injusta para pedirle a una persona, especialmente a la tasa que le pagan.

Punto. Se amable con otros. Y si debe mostrar su brillantez increíble, entonces, por favor, hágalo en la etapa de diseño, pero nunca lo haga en código.

1. GIT Hub! Tiene la capacidad de guardar su trabajo, al mismo tiempo, puede conservar todos sus códigos a pesar de que fueron editados por versiones. Git Hub guarda todo, así que esa es una buena manera de documentar su trabajo.

2. Una de las herramientas importantes: TODO. Asegúrese de usarlo religiosamente, le permitiría seguir su trabajo, al mismo tiempo, no “falsificar” ideas importantes, ya que siempre se desvanecen si no escribe algún tipo de sistema de notas para usted. Yo uso yokadi a través del repositorio apt-get. Es una gran herramienta.

Voy a sonar cínico, pero no es mi intención.

Generalmente no lo hacen.

Debe hacerse en registros de confirmación (para documentar cómo y por qué está cambiando el código), en el código mismo con nombres descriptivos y abstracciones de elección (para mostrar cómo se modela el área del dominio), selectivamente en código con comentarios (para explicar por qué las cosas se hacen cuando esto no está claro), en wikis en línea y README para ayudar a otros desarrolladores a orientarse, a través de pruebas automatizadas (que deben demostrar los criterios para un sistema de trabajo) y (según la estructura de la organización) en forma de manual.

En la práctica, pocas organizaciones aplican rigurosamente este tipo de documentación. Muchos registros de confirmación son espurios, incluso cuando se requieren (he visto algunos como “confirmación” o “cambios” o incluso “” – no hace falta decir que esto es algo que debe evitarse), la mayoría del código es una confusión porque las ideas de los autores eran confusos, los comentarios son generalmente alucinógenos o absurdos (“agrega uno a i” al lado de “i ++;”), los wikis generalmente están desactualizados, los README no existen o son simples y las pruebas unitarias a menudo simplemente verifican que el código escrito todavía está ahí.

Por supuesto, esto es simplemente una consecuencia de la Ley de Sturgeon, que establece que “el noventa por ciento de todo es una mierda”.

Aquí es donde debería escribir la llamada a las armas para documentar mejor, pero no lo haré. No lo haré porque probablemente lo sepas mejor y, si no lo sabes, deberías saberlo después de leer este hilo.

Pero hay otro ángulo para todo esto. Los desarrolladores de software generalmente escriben por dinero y el dinero habla. En general, los que pagan a los desarrolladores prefieren más funciones, más código, más parches, más actualizaciones de la documentación.

Y obtienen lo que prefieren, pero no siempre lo que quieren.

Por lo tanto, al final, documente lo mejor que pueda con lo que proporciona el usuario de su pequeño código.

Nada supera el código autodocumentado.

• Los wikis se vuelven obsoletos.
• Las API cambian en un instante.
• Los comentarios dentro de los métodos rara vez son utilizados por los clientes de nuestro trabajo.

Ejecutar sphinx, pydoc, javadoc o algo similar, automáticamente, cada vez que nos comprometemos es la mejor manera de hacerlo, en mi humilde opinión. Estuvimos de acuerdo en que parece excesivo en las primeras etapas, pero más tarde, ahorra tanto tiempo y disgusto que nos preguntamos por qué todavía hay personas que usan la entrada manual a los wikis para documentar cosas que cambian o que se vuelven obsoletas en un mes hora.

Al integrarse con git, artifactory y jenkins, obtenemos acceso a la documentación exacta de una versión arbitraria, con todas las ventajas de la integración continua y las pruebas continuas.

En general menos que adecuadamente.

En su defensa, el código bien escrito, claro, conciso, mantenible, extensible y escalable es mucho más valioso económicamente que un montón bien documentado de código de errores mal escrito.

A los programadores se les paga para crear valor económico.
Sí, no tiene mucho sentido documentar ampliamente las fallas.

Hay un número limitado de horas en el día.
A menudo, el intercambio comercial pragmático realista es un mejor código frente a más documentación.

Lo ideal es el código autodocumentado con una documentación mínima de alto nivel.

Esto es económicamente ideal porque mantener una extensa documentación detallada a menudo es prohibitivamente costoso.
La documentación detallada extensa a menudo desalienta las mejoras técnicas porque la documentación se convierte en un monstruo costoso que necesita alimentación.
El código que tiene un valor duradero siempre cambia.

Los proyectos rara vez (nunca) fallan como resultado de una documentación deficiente, a menudo fallan como resultado de un código deficiente.
La documentación puede ser lápiz labial en un cerdo (código pobre).
Esto no tiene sentido porque el siguiente paso es enterrar al cerdo, tirar el código y comenzar de nuevo.

1. Para desarrolladores: comentarios. La mayoría de los documentos externos no se leen, especialmente. si hay más de 2 páginas. E inmediatamente se desincroniza con el código que evoluciona rápidamente. Una hoja de ruta de alto nivel de dos páginas y un código bien comentado suelen ser buenos para mí. No soy fanático del volcado de ideas de Powerpoint.

2. Para la mesa de ayuda: Documento los “Diez problemas principales del usuario” con soluciones y se los proporciono a un equipo de la mesa de ayuda. Pueden manejarlos y escalar todos los demás. Sencillo.

3. Para usuarios: no leen el documento. Diablos, no leen instrucciones de dos oraciones en un correo electrónico. Así que trato de hacer que todo sea tan intuitivo que no lo necesiten. Pero si su software es una API, o está regulado por la FDA, o tiene muchas características no intuitivas (¡hablando con usted, Adobe CS!), Entonces alguien tendrá que escribir esas cosas. Una vez que contrate a un escritor técnico, tenga cuidado. Ahora es todo el trabajo de alguien rellenar ese documento hasta que haya una gran cantidad de capturas de pantalla y advertencias y procesos de 25 pasos … que 3 personas leerán. Haga que sea fácil para las personas encontrar lo que necesitan cuando lo necesitan.

Algunos: meses, años después,
actualizar su currículum;
otros: de largo aliento.

Mis tipos favoritos
limerick y el haiku
Elegante belleza.