Soy uno de esos desarrolladores que tiene la mentalidad de que el código escrito debe explicarse por sí mismo y leerse como un libro. SIN EMBARGO, cuando desarrollo código de biblioteca para que otras personas lo usen, trato de poner tanta documentación en los archivos de encabezado como sea...
Me pregunto qué debería contener la documentación de un algoritmo. No se puede encontrar una directriz adecuada para seguir. Tengo en mente incluir resumen del algoritmo descripción del algoritmo diagramas de flujo pseudocódigos conjunto de datos de entrada de muestra (múltiple) datos...
Me parece que no es posible escribir una especificación de software en inglés que esté completamente libre de ambigüedades, simplemente debido a la naturaleza informal del lenguaje natural, y por lo tanto, una especificación verdaderamente inequívoca debe incluir código escrito en un lenguaje...
Una parte central del diseño impulsado por dominio es el uso constante de un lenguaje ubicuo en todo el sistema: en conversaciones, código, esquema de base de datos, interfaz de usuario, pruebas, etc. Estoy involucrado en un proyecto en el que ya existe un lenguaje de dominio bien establecido,...
Soy un defensor del código debidamente documentado, y soy muy consciente de las posibles desventajas del mismo . Eso está fuera del alcance de esta pregunta. Me gusta seguir la regla de agregar comentarios XML para cada miembro público, considerando cuánto me gusta IntelliSense en Visual...
Cerrada . Esta pregunta necesita estar más centrada . Actualmente no está aceptando respuestas. ¿Quieres mejorar esta pregunta? Actualice la pregunta para que se centre en un problema solo editando esta publicación . Cerrado hace 5 años . El equipo en el...
Donde trabajo actualmente es el enfoque general: evitar la documentación tanto como sea posible Solo documente si un equipo diferente lo necesitará solo para aclarar, no me refiero a la documentación del código; esto lo hacemos, me refiero a toda la documentación que rodea el proceso de diseño,...
Estamos usando métodos ágiles en mi proyecto actual en este momento, y tenemos un montón de historias como estas: Como asistente, quiero pagar un reembolso a un cliente para que pueda obtener algo de dinero cuando lo solicite. Como cliente, quiero pagar una compra para poder recibir mi...
Soy un desarrollador aficionado y todos mis programas hasta ahora eran lo suficientemente simples como para documentarse en el código. Mientras leía el código, estaba claro lo que estaba haciendo tal y tal acción (mi prueba estándar fue mirar el código 6 meses después y entender todo a la primera...
Creamos una biblioteca comercial y ejemplos de código que están siendo utilizados por desarrolladores externos. Tenemos documentación (cerrada, disponible para usuarios registrados) que explica ampliamente cómo usar la biblioteca. Muchos de los desarrolladores son usuarios nuevos, por lo que se...
Solía ser un fanático de requerir comentarios XML para la documentación. Desde entonces he cambiado de opinión por dos razones principales: Como un buen código, los métodos deben explicarse por sí mismos. En la práctica, la mayoría de los comentarios XML son ruidos inútiles que no...
He documentado mi código doxygen, pero no quiero el HTML predeterminado que proporciona. Sé que puedo personalizarlo al proporcionar CSS personalizado, encabezados, pies de página, etc. (como lo hace GNOME), y cómo puedo agregar código PHP común a los archivos y decirle que guarde como .php, pero...
¿Qué información esperarías ver en el archivo README de github? ¿Debería ir todo en el archivo README? es decir Introducción Instalación Versiones Guía del usuario Implementación Pruebas Recursos Relacionados ¿O debería simplemente poner ciertas cosas en el archivo README (Introducción,...
Estoy trabajando en una pequeña biblioteca que proporciona implementaciones de métricas de cadena básicas y bien conocidas. Principalmente para mi propia educación. Entonces, el desarrollo ocurre cada vez que tengo un poco de tiempo libre. Debido a esto, he automatizado la mayoría de los procesos...
Entonces está solucionando errores, luego encontró uno que podría afectar a otros módulos del producto de software. Sus datos no son suficientes para respaldar su reclamo sobre los efectos de la corrección y se le pidió que creara un documento de análisis de impacto. ¿Hay un proceso definido...
¿Alguien tiene sugerencias para crear una representación de diagrama de flujo de una interfaz web de estilo REST? En el interés de proporcionar documentación exhaustiva a los co-desarrolladores, he estado jugando en el dia modelado de la interfaz para modificar y generar un recurso de...
Quiero escribir Javadoc en SECO. Pero el documento de Oracle sobre Javadoc dice escribir lo mismo nuevamente en el comentario del método de sobrecarga. ¿No puedo evitar la
Al revisar de otro programador implementación de una función para calcular la CDF distribución normal , hice una sugerencia para reemplazar toda la implementación de Python con funciones integradas o utilizar SciPy, una biblioteca científica común. Otro programador señaló que math.erfc()ni...
Estoy a punto de abandonar un proyecto, y antes de irme, mi jefe me ha pedido que documente el código (no lo he documentado muy bien). No es gran cosa, el proyecto no es terriblemente complejo. Pero estoy encontrando lugares en mi documentación donde me gustaría decir: "Observe en la línea XYZ que...
Esto se refiere a una discusión en una respuesta y los comentarios de esta pregunta: ¿Qué pasa con la aversión a la documentación en la industria? . La respuesta afirmaba que "el código no puede mentir" y, por lo tanto, debería ser la ubicación de acceso en lugar de la documentación. Varios...