documentation - fuente - generar documentacion visual studio 2017
¿Qué es menos molesto: no hay documentación de código fuente o documentación de código incorrecto? (17)
Hoy tuve una discusión con un colega sobre uno de sus comentarios como resumen de un método. En su mayoría no está escribiendo ningún resumen, pero en este caso agregó uno y fue realmente malo: no se describió lo que el método está haciendo, asumió lo que el método puede estar haciendo. Debo agregar que este código no era suyo, era código heredado.
Le dije que en este caso nunca debería haber hecho ningún comentario, solo después de comprobar realmente lo que está ocurriendo allí, porque alguien que lea su opinión como una declaración válida no lo comprobará solo y lo arruinará. Podría haber agregado "Esto es una suposición, por favor verifíquelo usted mismo". pero no lo hizo. Incluso si no hubiera ningún comentario, sería mejor porque el desarrollador debe verificarlo por sí mismo.
Personalmente, soy muy estricto con la documentación del código. Eso no significa que comento cada línea de código, pero los resúmenes de métodos, clases, etc. son obligatorios y las líneas adicionales para partes de códigos difíciles también ayudan.
Debo agregar que trabajo en un equipo de 10 desarrolladores donde nadie escribe código solo. Pasar menos tiempo en la documentación del código significa que otros desarrolladores están dedicando más tiempo a obtener el significado del código.
Ni siquiera puedo decir si me gusta menos documentación que este tipo de mala documentación. Pero al final, creo que paso más tiempo con un código extranjero documentado que no es bueno. Entonces ... odio los dos. ;)
¿Qué piensas? ¿No te importa o ves estas cosas en tu trabajo diario también? Lo que es peor para usted: ¿no hay documentación de código o documentación de código incorrecta?
¡Gracias!
Miguel
"La documentación es como el sexo, cuando es bueno, es muy, muy bueno, y cuando es malo, es mejor que nada. (Dick Brandon)"
No en serio, tienes un problema cuando la documentación es completamente incorrecta. Si es simplemente malo (porque es vago o incompleto, por ejemplo), al menos puede estar contento de que esté allí. Esto se nota muy rápidamente cuando se trabaja con algunas API completamente indocumentadas. MSDN está lleno de ellos, donde la documentación es incompleta e imprecisa, pero sigue siendo mucho mejor que nada.
Encuentro que la calidad del código tiene mucho más que ver con mi capacidad para trabajar en él que con la calidad de la documentación.
He estado trabajando en un código que casi no estaba documentado (con comentarios que aparecían solo ocasionalmente), pero que todavía era perfectamente comprensible. También trabajé en un código que tiene montones de documentos y virtualmente cada línea comentada, pero casi imposible de trabajar.
La mala documentación es ciertamente extremadamente molesta, pero peor es el código que es tan intrincado y mal diseñado que necesita buscar a tientas páginas y páginas de documentos para hacer cualquier cosa .
La documentación incorrecta es peor que la falta de documentación.
La documentación incorrecta que parece autoritativa es peor que la falta de documentación.
Documentación incompleta es mejor que ninguna documentación.
La documentación especulativa que está marcada como tal es, a menudo, mejor que ninguna documentación.
La mala documentación a menudo está en un código peor, diría que la mala documentación sobre un buen código puede ser un problema, pero ¿con qué frecuencia ves eso?
Si se trata de una ayuda de alguien que ha trabajado antes en el código, puede darle una advertencia.
Si es del autor original, tal vez puede ofrecer una idea de su mentalidad retorcida, tal vez puede ser la clave para desentrañar un desastre - o le avise que algún código que está a punto de refactorizar es más complicado que usted ". D pensar a primera vista.
Veo a mucha gente diciendo que la mala documentación es peor, pero no se puede presentar un solo escenario (y nunca he visto uno) donde en realidad era peor.
Por lo general, escuchas gritos contra la documentación de personas que realmente no entienden lo que hace y no puede hacer su propio código, por lo tanto, lo comentan correctamente. (IE: son los autores del escenario de código / comentario incorrecto actualmente en discusión)
La mala documentación es peor que la falta de documentación. Sin embargo, yo argumentaría que, en la medida de lo posible, su código debería ser autodocumentado. es decir, debe elegir nombres significativos para las entidades en su código y tener métodos cortos. Los comentarios que explican qué está haciendo el código deberían ser virtualmente redundantes, porque están claros desde el código mismo. Los comentarios se usarían principalmente para explicar POR QUÉ su código está haciendo algo.
La mala documentación es peor. La mala documentación a menudo miente (involuntariamente o no), lo que puede llevarlo por el camino equivocado desde el principio. Los documentos incorrectos pueden evitar que te des cuenta de tu error porque piensas que estás equivocado cuando algo no funciona, cuando en realidad nunca fue así. Los documentos incorrectos también pueden afectar su percepción de la calidad general del producto, ya que no puede estar seguro si el comportamiento que está viendo es una documentación incorrecta o un error real en el código.
Preferiría tener buenos documentos, por supuesto, pero dada la opción entre documentos malos y simplemente trabajando lentamente a través del código fuente, tomaré la opción de fuente.
Ninguna documentación es mucho mejor. Preferiría tener que entenderlo por mi cuenta antes que ser engañado por una guía incorrecta.
No hay documentación es mejor. Me han mordido documentos engañosos y me he resignado a ser cínico sobre lo que dice. En la mayoría de los casos, generalmente es lo que el desarrollador quería hacer en lugar de lo que realmente hace (especialmente en ausencia de prueba: /)
Si tuviera que elegir, preferiría tener documentación de código incorrecta. Dado que la mala documentación de la fuente puede deletrear horror por código confuso más adelante, hacer adiciones al código casi imposible.
Un problema con cualquier cosa que no sea la documentación completa o nula es que puede confundir la documentación incorrecta o incompleta con la documentación completa y precisa, y la documentación deficiente puede llevar a ninguna (¿por qué el código del documento? Todos sus comentarios son incorrectos).
Preferiría que no haya documentación en la documentación incorrecta.
hmm ... la pregunta que debe hacerse es: ¿es mala la documentación incorrecta, o es que es correcta y el código está equivocado?
por ejemplo, el resumen dice "esta rutina hace xyz", pero el código realmente lo hace de una manera extraña. Si a menudo puede ser que el resumen es correcto, eso es lo que el código debería estar haciendo, pero el autor era un completo nincompoop.
Lo he visto con mayor frecuencia cuando se trata de códigos de devolución, el resumen proporciona un buen conjunto de códigos que deberían devolverse, pero la rutina devuelve 0 cada vez.
En cualquier caso, es un error y debe corregirse o al menos marcarse con un comentario. ¿Documentación ''mala'' que se actualiza, incluso con solo ''WTF?'' marcas, es mejor que ninguna documentación. La documentación que parece obsoleta simplemente no se lee.
Una última cosa: elegir "documentación incorrecta" es mejor que oficialmente no escribir documentación porque podría ponerse mal más tarde. Los programadores siempre encuentran excusas para no escribir comentarios :-)
Ninguna documentación es mucho mejor.
De hecho, estoy dispuesto a dar un paso más. Mantenga la documentación a un alto nivel y no documente demasiados detalles.
Una vez que tenga una comprensión decente de la estructura de alto nivel, no es mejor documentar que comprender el código leyendo el código.
No confío en nadie que trabaje en un módulo que no entienda lo que el código de ese módulo realmente está haciendo. Si desea usar el módulo como una caja negra, bien, lea el documento. Si desea cambiar su comportamiento, es casi mejor que no le entregue la documentación y que descubra qué hace en todos los casos.
Si los desarrolladores (es decir, los usuarios de las API) tienen acceso al código fuente, entonces la documentación incorrecta es peor que la falta de documentación. Pero al menos una vez que los usuarios descubrieron que la documentación es mala, pueden consultar el código fuente para encontrar las respuestas a sus problemas.
Si los desarrolladores no tienen acceso al código fuente, entonces la documentación incorrecta puede ser mejor que la falta de documentación, dependiendo de qué tan simples sean realmente las API y qué tan mala es la documentación. Si la documentación es realmente mala y el código fuente no está disponible, es posible que el usuario tenga que dejar de usar las API por completo.
La documentación del código es importante, pero es completamente insignificante en comparación con la Unidad / Aceptación / Pruebas funcionales. (Cuando digo code doc estoy tomando aproximadamente por método / clase doc no alto nivel design / api doc).
Lo que su colega debería haber hecho fue escribir un montón de pruebas para respaldar su suposición y luego cambió el documento.
Esto obviamente entra en territorio subjetivo, pero basado en mi definición de mala documentación, ¡es mucho peor que no tener documentación!
Para ayudar a definir eso más claramente, una vez tuve un compañero de trabajo que escribió el peor tipo de documentación posible. Se centró solo en implementaciones y nunca escribió documentación en los encabezados (donde se definen las interfaces públicas).
Ella no era floja en absoluto. Con cada archivo fuente de implementación, ella escribió un manual (descrito como tal con una tabla de contenidos y todo). Cada uno tenía al menos una docena de páginas y, a veces, hasta 30 páginas. Este manual trata casi completamente de cómo se implementó el código y, a menudo, es incluso más largo que el código en sí (en general, toma menos tiempo para leer y comprender el código que el manual). También fue francamente aburrido, describiendo detalles que, por lo general, serían evidentes, por ejemplo, cómo se usan las variables, etc.
El problema con la documentación que enfatiza tanto los detalles de implementación es que los detalles de implementación cambian (las interfaces no tanto). El resultado es que muchas implementaciones cambiaron, pero estos manuales no se actualizaron. No pasó mucho tiempo antes de que los manuales fueran incorrectos y engañosos y conducen a los desarrolladores a hacer suposiciones incorrectas. Con estas suposiciones erróneas surgieron muchos errores sutiles.
Si no hubiera habido documentación en absoluto, es posible que haya habido suposiciones erróneas y errores como resultado, pero al menos esos errores no hubieran provenido de la documentación en sí. También aprendí cuánto más importante es centrarse en las interfaces en primer lugar para la documentación, ya que las implementaciones realmente tienden a cambiar con el tiempo. Si la interfaz se documenta de forma adecuada, las implementaciones generalmente pueden ser entendidas por alguien con la experiencia adecuada e incluso reemplazadas por completo si la interfaz es comprensible, pero la documentación que solo se enfoca en la implementación tiende a desaparecer con bastante rapidez.
SI tiene un buen código, entonces no necesita ninguna documentación. "Buen código" quiero decir que cada función tiene un nombre que se explica por sí mismo, el propósito de la función es claro, etc.
Lo único que se debe comentar son los métodos MUY OPTIMIZADOS que se sacrificaron para la optimización. Pero eso no debería ser más de 3-5 funciones por aplicación: por lo general, solo el 20% de la aplicación causa problemas de rendimiento (o cualquier otro problema). Y solo la optimización del 20% de esos 20% (el 4% de toda la aplicación) podría ser fructífera para optimizar.
Cuantos menos comentarios haya en el código: el código más legible es (consulte Steve McConnel (http://www.stevemcconnell.com/books.htm) y otros)