Preguntas etiquetadas con documentation

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 escrito". Mi pregunta es la …

236 programming-practices  documentation  comments 

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

155 documentation 

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 …

112 documentation  standards  help-documentation 

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 clase específica (y …

104 documentation  large-scale-project 

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 cambio, debería haberse …

94 version-control  documentation 

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 comentarios para …

86 documentation  comments 

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()); boutique.setNom(fluxBoutique.getNom()); boutique.setSelected(false); boutique.setIdWebSC(fluxBoutique.getId()); boutique.setDateModification(new Date()); boutiqueDao.persist(boutique); } else { boutique.setSite(site); boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo()); boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl()); boutique.setNom(fluxBoutique.getNom()); //boutique.setSelected(false); boutique.setIdWebSC(fluxBoutique.getId()); boutique.setDateModification(new Date()); boutiqueDao.merge(boutique); } Hay una línea comentada aquí. Pero creo que aclara el código al hacer obvio cuál …

83 documentation  comments 

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 …

78 documentation  comments 

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 proyecto …

72 project-management  documentation 

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

66 career-development  documentation 

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 grandes en otras más pequeñas. Pero lo …

63 programming-practices  code-quality  documentation 

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 manera más detallada. …

60 documentation  automation  automatic-programming 

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 desarrollador, he usado …

59 documentation  component  jargon 

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 { get; …

54 programming-practices  documentation  language-agnostic 

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 .gitignore?

49 git  documentation