¿Tiene un hábito de tal manera que cuando se está codificando , se escribe la documentación así, y asegúrese de que están en sincronía.Cómo escribir la documentación al programar
¿Cómo se puede lograr eso? ¿Qué escribes? La función es lógica? ¿El concepto? O otras mejores prácticas? Gracias en avance!
Soy un programador python y escribo mucho doctests, que es un módulo python que le permite escribir pruebas como ejemplos del uso de funciones en la cadena de documentación de cada función. Echar un vistazo al ejemplo de here:
def factorial(n):
"""Return the factorial of n, an exact integer >= 0.
If the result is small enough to fit in an int, return an int.
Else return a long.
>>> [factorial(n) for n in range(6)]
[1, 1, 2, 6, 24, 120]
"""
Las dos últimas líneas son un ejemplo del uso de la función, y se puede ejecutar mediante el módulo doctest. De esta manera, usted logra eso:
Normalmente comienzo con la creación de funciones y la redacción de los doctests, para tener una idea de cómo funcionará cada función y cuáles son las entradas/salidas esperadas; Gracias a este enfoque, siempre tengo al menos una breve documentación de cada función y módulo que escribo.
De vez en cuando, escribo un documento más extenso que explica cómo se pueden usar mis módulos (para mis colegas) y siempre uso la sintaxis doctest; sin embargo, siguiendo su pregunta, nunca hago más que esto, a veces puedo escribir un comentario en un blog sobre mi trabajo o en una biblioteca que escribí, pero no tengo tiempo para escribir documentación más larga.
¡Bien, gracias por aceptar la respuesta! :) Estoy seguro de que existe algo así como "doctest" para muchos otros idiomas también. – dalloliogm
No, pero puede usar la sintaxis de comentario XML para ayudarlo a lograrlo. Le permitirá documentar sus clases, propiedades y llamadas de método al menos. Luego puede usar la automatización de compilación para construir un archivo CHM para usted. Investiga Sandcastle por esto.
De lo contrario, es útil una wiki que ayude a rastrear la colaboración de su equipo. Muy a menudo estas cosas se convierten en "grupos de información" donde las personas describen algo sobre el sistema. Estos pueden ser utilizados para construir documentación también.
Finalmente, pueden crearse notas de la versión si tiene integración con su tienda de rastreo. Por ejemplo, TFS le permitirá obtener todos los elementos de trabajo y conjuntos de cambios para cualquier compilación determinada, lo cual es bastante útil para compilar notas de la versión.
XML es el lenguaje del diablo. Estoy tentado de menospreciar ... – hasen
Escribo la estructura de la documentación antes de comenzar y la cambio mientras estoy escribiendo. Yo uso Diseño por contrato como una estructura de qué escribir en la documentación:
http://en.wikipedia.org/wiki/Design_by_contract
Realmente quiero llegar a este lugar y admirarte por hacer esto ya. –
Esos elementos deben estar preferiblemente en la especificación de diseño (dependiendo del dominio del problema). El resto me gusta escribir en el código con etiquetas específicas y luego crear la documentación automáticamente. Una herramienta excelente para esto es doxygen, pero hay muchos otros.
De esta manera, la documentación se realiza de forma casi automática ya que me gusta comentar mi código mientras trabajo en él.
Depende del contexto de la documentación. Si lo está documentando para otros desarrolladores, entonces tengo la opinión de que las pruebas de unidades decentes y la nomenclatura variable con comentarios, entonces el código se auto documentará.
En el contexto de API externas para que los clientes utilicen, normalmente tomo el enfoque de documentar el elemento cuando termino de escribir esa funcionalidad.
Esto me ayuda a documentar a medida que avanzo.
en esencia, son herramientas simples para recopilar ideas y luego son fáciles de poner en documentos más grandes si es necesario. Usar buenas herramientas Uso livewriter, mediwiki, snagit, onenote y freemind.
Odio escribir documentos, por lo que recopilo ideas a medida que avanzo.
El código bien escrito y bien comentado no debería necesitar mucha documentación adicional del programador. En cuanto a los documentos del usuario final, escribo los archivos de ayuda para mis aplicaciones al mismo tiempo que implemento cada función, y los tutoriales cuando he realizado la mayor parte de la codificación. Sin embargo, he llegado a pensar que escribir los tutoriales anteriormente en el proceso sería una mejor idea.
Esto parece una especie de refrito de su pregunta anterior: http://stackoverflow.com/questions/1220319/how-to-design-software – Amber
no es lo mismo. lo anterior es cómo diseñar como gerente. y esta pregunta que quiero saber para ser un programador, ¿qué debo marcar? Gracias – MemoryLeak
Ah, ya veo. Debido a la fraseología de ambos, no fue tan claro para mí. Gracias por aclararlo. – Amber