La documentación del software es un texto escrito que acompaña al software de la computadora. Explica cómo funciona el software, cómo instalarlo, cómo usarlo y otros recursos para obtener ayuda.
Mucha gente afirma que "los comentarios deberían explicar 'por qué', pero no 'cómo'". Otros dicen que "el código debe autodocumentarse" y los comentarios deben ser escasos. Robert C. Martin afirma que (reformulado a mis propias palabras) a menudo "los comentarios son disculpas por código mal...
Se me ha pedido específicamente que brinde una explicación o comentario línea por línea (o según corresponda, por ejemplo, imagen por imagen, etc.) que mi jefe quiere poder leer y seguir. Como no es programador, no puede seguir el código, por lo que quiere que todo esté traducido al inglés. ¿Se...
El estándar RFC 2606 reserva los nombres de dominio example.org , example.net y example.com con el propósito de ser utilizados como ejemplos en la documentación. ¿Qué es un equivalente para un número de teléfono (incluido el código de país) que se puede usar como ejemplo, por ejemplo, para dar a...
Supongamos que estoy desarrollando un proyecto relativamente grande. Ya he documentado todas mis clases y funciones con Doxygen, sin embargo, tuve la idea de poner "notas de programador" en cada archivo de código fuente. La idea detrás de esto es explicar en términos simples cómo funciona una...
Durante una reunión sobre la reversión de un SDK de un tercero desde la última versión, se observó que nuestros desarrolladores ya señalaron en el historial de confirmación que la última versión no debería usarse. Algunos desarrolladores argumentaron que esta era una mala práctica y que, en...
Estoy trabajando en un proyecto bastante grande y tuve la tarea de hacer algunas traducciones para él. Hubo toneladas de etiquetas que no se han traducido y mientras buscaba el código encontré este pequeño fragmento de código //TODO translations Esto me hizo pensar en el sentido de estos...
Escribí el siguiente código: if (boutique == null) { boutique = new Boutique(); boutique.setSite(site); boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo()); boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());
En primer lugar, en esta pregunta me gustaría mantenerme alejado de la polémica sobre si los comentarios de código fuente son buenos o malos. Solo estoy tratando de entender más claramente lo que las personas quieren decir cuando hablan de comentarios que te dicen POR QUÉ, QUÉ o CÓMO. A menudo...
Estuve trabajando en un proyecto hace tres meses, y de repente apareció otro proyecto urgente y me pidieron que cambiara mi atención. A partir de mañana, regresaré al antiguo proyecto. Me doy cuenta de que no recuerdo qué estaba haciendo exactamente. No se donde empezar. ¿Cómo puedo documentar un...
Estoy planeando dejar mi trabajo actual porque estamos encerrados en el uso de Blub , con un marco empresarial de Blub y un servidor web de nivel Blub, en un alojamiento mediocre compartido. Mis compañeros de trabajo son amables y mi jefe es el propietario promedio de una pequeña empresa. Quiero...
Entiendo la importancia de un código bien documentado. Pero también entiendo la importancia del código autodocumentado . Cuanto más fácil sea leer visualmente una función en particular, más rápido podremos avanzar durante el mantenimiento del software. Dicho esto, me gusta separar las funciones...
La generación automática de documentación se puede hacer con una variedad de herramientas, siendo GhostDoc una de las más destacadas. Sin embargo, por definición, todo lo que genera es redundante. Echa un vistazo a los nombres de métodos, clases, etc. y genera inglés que podría explicarlos de...
Estoy escribiendo documentación de usuario (un SOP) que involucra programas de terceros que estoy tratando de describir bien. Uno de estos programas es un servidor que ofrece poca indicación de su inicio además de un gráfico que se muestra durante su rutina de inicialización / inicio. Como...
A veces me encuentro en situaciones en las que la parte del código que estoy escribiendo es (o parece ser ) tan evidente que su nombre se repetirá básicamente como un comentario: class Example { /// <summary> /// The location of the update. /// </summary> public Uri UpdateLocation...
Cuando usa herramientas como jsdocs , genera archivos HTML estáticos y sus estilos en su base de código en función de los comentarios en su código. ¿Deben registrarse estos archivos en el repositorio de Git o deben ignorarse con
Uno de los objetivos principales de las empresas de desarrollo de software es aumentar su factor Bus. Esto también es defendido en una charla organizada por Google . Eso significa que debe codificar y documentar todo de una manera que si mañana lo atropella en autobús, el proyecto aún puede...
Parece haber una aversión a escribir incluso la documentación más básica. Nuestro proyecto READMEs es relativamente simple. Ni siquiera hay listas actualizadas de dependencias en los documentos. ¿Hay algo que desconozco en la industria que haga que a los programadores no les guste escribir...
Cuando trabajo en código, enfrento muchos de los mismos desafíos que enfrentan mis compañeros de equipo, y he escrito algunas funciones y clases útiles, y ellos también. Si hay una buena comunicación, escucharé sobre algo genial que alguien armó, y seis meses después, cuando lo necesite, lo...
Me encuentro escribiendo (con suerte) comentarios útiles en la documentación del código (C ++) del tipo: The reason we are doing this is... La razón por la que uso "nosotros" en lugar de "yo" es porque hago mucha escritura académica donde a menudo se prefiere "nosotros". Así que aquí está la...
El programa de CS de mi escuela evita cualquier mención de programación orientada a objetos, por lo que he estado leyendo un poco para complementarlo, específicamente, Construcción de software orientado a objetos por Bertrand Meyer. Meyer señala repetidamente que las clases deben ocultar tanta...