¿Puede el código ser la documentación en herramientas de desarrollador de código abierto? ¿Con qué frecuencia es?

7

Es comprensible que después de un gran esfuerzo de desarrollo, algunos autores de OSS consideran razonable que los usuarios del proyecto también deben hacer un esfuerzo para comenzar.

¿Puede el código fuente ser efectivamente la documentación del proyecto? ¿Necesita estar estructurado de una manera particular para lograr esto? ¿Y con qué frecuencia se toma este enfoque?

Por supuesto, esto solo sería factible si el proyecto está dirigido a desarrolladores, y está escrito en el mismo idioma específico de la aplicación (por ejemplo, no puede entender motor V8 solo con JavaScript).

    
pregunta vemv 31.10.2011 - 17:26

6 respuestas

11

NHibernate es OSS. Puede descargar el código fuente de forma gratuita, realizar sus propios cambios, volver a compilarlo, enviar ese código fuente al VCS, etc., etc. ¿Le exige a Ayende que revise el código, y el de DynamicProxy de Castle, para poder usar de manera efectiva? ¿Su biblioteca para implementar su capa de persistencia? Por supuesto no. La comunidad de NHibernate proporciona un buen conjunto de documentación y mejores prácticas para usar la biblioteca de NHibernate. Del mismo modo, el complemento Fluent NH tiene una documentación decente; no tiene que revisar el código de la biblioteca para averiguar qué hace y cómo usarlo.

En resumen, incluso OSS debe ajustarse al "principio de caja negra" desde la perspectiva del usuario final.

Los codificadores esperan que sus bibliotecas se empaqueten de manera muy parecida a su equipo electrónico: esperan recibir un manual de instrucciones junto con esta "caja negra", que les dice cómo conectarlo y cómo comunicarse con él. Si no reciben un manual, los más inteligentes verán lo que viene en el paquete, esperarán ver etiquetas muy claras de dónde se enchufan las cosas y asumirán que no se requieren conocimientos especializados para su funcionamiento una vez que está configurado correctamente. Si ninguno de estos es cierto, es probable que el programador llame a los desarrolladores de la biblioteca en busca de ayuda, como si estuviera llamando a soporte técnico si no tuviera toda la información que necesitaba para configurar su TiVo. Lo último que harías es romper el sello de un equipo nuevo y con garantía y tratar de rastrearlo tú mismo, de manera muy similar a lo que haría el programador es arrancar y rastrear el código fuente de la biblioteca para una pista sobre su funcionamiento interno.

De manera similar, los proyectos OSS que no están documentados de manera efectiva de otra manera que no sea el código, se clasifican en una de tres categorías:

  • proyectos infantiles : la documentación simplemente no está bien desarrollada porque se centra en la prueba de concepto y, por lo tanto, en el código de trabajo. Los usuarios del código en esta etapa son evaluadores "beta" y entienden su naturaleza "tal cual" en todos los frentes, incluida la documentación.
  • extremadamente simple : el propósito declarado de la biblioteca, los nombres y las firmas de las clases y los miembros de la clase tal como se ven desde algún navegador de objetos o por JavaDocing the JAR, y quizás una simple demostración, le dicen al usuario todo lo que necesita saber.
  • muerto o moribundo : nadie quiere tomarse el tiempo para averiguar cómo usar la biblioteca por prueba y error, o por inspección, por lo que nadie la está utilizando.
respondido por el KeithS 31.10.2011 - 17:44
6

El código fuente no es una documentación.

He visto demasiados (excelentes) proyectos sin documentación, solo código fuente y algunos tutoriales. Mi último ejemplo es Lutece (un CMS francés: pasé mucho tiempo para entender cómo usarlo y qué puedo hacer con él. Fue horrible).

Idealmente, la documentación se escribiría cuando esté desarrollando su aplicación. Desafortunadamente, muchas personas no escriben ninguna documentación (no Javadoc para proyectos Java, ...), y creen que los colaboradores escribirán tutoriales, wikis, documentación. Si no hay documentación inicial, nadie intentará ayudarlo, ni descubrirá su trabajo.

Si puede hacer una buena documentación y tiene suficiente tiempo, por favor, hágalo;)

    
respondido por el gros_bidule 31.10.2011 - 18:01
3

No, no creo que el código deba ser la documentación. Y no creo que importe tanto si es un proyecto de código abierto como si no.

La falta de documentación (aparte del código en sí) será un desvío para muchos usuarios y contribuyentes potenciales. He abandonado o evitado el uso de algunas bibliotecas para otras bibliotecas de código abierto simplemente porque los tutoriales muy escasos eran demasiado simplistas (los usos empresariales reales eran más complejos y se necesitaban detalles que nunca se explicaron o documentaron claramente) y la documentación de la API fue muy escasa más de function: SetParamX() - This sets param X . El código por sí solo tampoco captura fácilmente los requisitos o especificaciones comerciales de alto nivel, como param X must be a valid subnet mask, unless param Y is set to "foo" . Para deducir este requisito, es posible que tenga que leer 100 líneas de código y saltar de 3 o 4 capas de llamadas a métodos para averiguar exactamente qué es este requisito.

¿Qué tan ansioso estaría usted por trabajar en un proyecto que usted mismo ha descifrado solo con el código? Sé que no lo haría, ya sea un proyecto de código abierto o un proyecto corporativo interno. Al menos con los proyectos internos (al menos aquí), esto rara vez, pero no nunca, es un problema, y si sucedió con un proyecto interno, probablemente podría encontrar a la persona que escribió el código y preguntar Las preguntas.

    
respondido por el FrustratedWithFormsDesigner 31.10.2011 - 18:17
1

La documentación de Word significa muchas cosas, y para la mayoría de los proyectos de código abierto, eso es un problema.

Al dejar de lado muchos detalles, lo clasificaría principalmente en tres partes:

  1. Documentación del usuario final: donde es probable que las personas usen solo el producto final. Por mucho, lo más común y mínimo que encuentras en los proyectos OSS es "página de manual".

  2. Documentación de la API: aquí usted asume que la gente está mirando las partes internas de sus módulos, pero solo como una caja negra, principalmente al vincular las bibliotecas. (por ejemplo, use una biblioteca de códecs de video para construir su propio reproductor de medios). Uno de los excelentes ejemplos es GNOME, documentación de GTK para desarrolladores de aplicaciones.

  3. Documentación para desarrolladores: aquí es donde se supone que las personas realmente van a contribuir a la lógica interna central para mejorarla o ampliarla.

La necesidad y el método para crear los tres tipos de documentación son diferentes.

  • La documentación de nivel de usuario final ciertamente no se puede hacer dentro del código. Típicamente estos son documentos externos como el manual del usuario; no pueden estar dentro del código (incluso si se llevan dentro del tar.gz de los códigos fuente).

  • La documentación de la API a menudo se puede hacer (y generalmente se hace mejor) utilizando el tipo de marco doxygen, donde los comentarios sobre las funciones se pueden traducir en páginas con formato completo. De esta manera, se guardan los esfuerzos de formateo y se logra la consistencia, mientras que los detalles centrales de la documentación aún están escritos a mano. Además, podemos ver que cuando la API evoluciona o se vuelve incompatible, la modificación de comentarios puede ayudar a facilitar la documentación de la nueva versión. Otra cosa que he visto es escribir un pequeño archivo "api_example.c" que explica cómo usarlo. Para la mayoría de los proyectos de tamaño mediano esto es suficiente.

  • Por último, pero más importante es la documentación de diseño que explica el funcionamiento interno del código. Difícil de decir, pero esto es raro incluso en empresas pagadas profesionalmente. Muchas compañías prefieren hacer "documentos de diseño" en algún lugar fuera del código, pero desafortunadamente, a medida que el código evoluciona, estos permanecen desconectados de los documentos. En tal escenario, tener muchos comentarios y comentarios sobre los comentarios en realidad ayuda mucho mejor. Por lo general, está NO completo, pero la mayoría de las veces, si el desarrollador es lo suficientemente inteligente, lo que realmente importa es comentar todas las partes no obvias en abundancia. Este enfoque siempre funciona mucho mejor.

De hecho, teniendo esto en cuenta, uno debería preocuparse por redactar documentos de nivel superior solo para explicar la terminología y la lógica de negocios más amplia y dejar los detalles explicados dentro del código (y dejar que evolucione junto con el código). Los documentos externos casi siempre nunca evolucionan tan rápido como el código, por lo que deben limitarse en cuanto a dependencias y detalles.

Dipan.

    
respondido por el Dipan Mehta 31.10.2011 - 18:24
1

Si desea que el proyecto OSS sea un éxito, realmente debe proporcionar una amplia documentación para los usuarios. La mayoría de los proyectos OSS tienen una base de usuarios relativamente pequeña que se preocupa por ahondar en el código.

Si no estoy contribuyendo directamente al proyecto de alguna manera, la única vez que miro el código fuente es cuando siento que he descubierto un error y deseo corregirlo por mí mismo o notificar al proyecto el error. Encontré y en qué parte del código siento que está el problema.

No puedo decir cuántas veces he evaluado un proyecto OSS complejo para no encontrar ninguna documentación sub-esencial en absoluto. Muchas veces, si tengo otra opción más transparente, iré en esa dirección en parte porque no deseo pasar días de prueba y error para averiguar cómo usarlo, o porque creo que el proyecto es demasiado "verde" o demasiado " Amateur "para comprometerse.

    
respondido por el maple_shaft 31.10.2011 - 18:24
1

Casi todos los paquetes populares de Java OSS que he usado han sido bien documentados con javadocs. Para ser técnico, esto significa que el código fuente contiene, no es, la documentación.

En cualquier caso, estos son generalmente algunos de los sistemas mejor documentados que he usado. Creo que esto se debe a mantener los documentos con el código fuente, lo que permite que se actualicen en paralelo y luego se dividan los documentos más adelante.

    
respondido por el Bill K 31.10.2011 - 22:24

Lea otras preguntas en las etiquetas