¿Cómo pueden tener éxito los proyectos de código abierto sin documentación sobre su diseño o arquitectura?

11

Quiero mejorar mis habilidades de programación estudiando famosos proyectos de código abierto, pero creo que es fácil perderse simplemente saltando a su código fuente.

Así que decidí leer su documentación sobre su diseño o arquitectura (como los diagramas UML) para tener una idea general sobre la organización de su código primero. Sin embargo, para mi sorpresa, no puedo encontrar ninguna documentación arquitectónica para grandes proyectos de código abierto como Hibernate, Spring, ASP.NET MVC, Rails, etc.

Así que comencé a preguntarme: ¿cómo puede un proyecto de código abierto tener éxito si los desarrolladores recién llegados no tienen documentación arquitectónica / de diseño para leer, o si el gerente del proyecto acaba de abrir el código fuente pero cerró su documentación?

open-source documentation asp.net-mvc

— TomCaps
fuente

3

"más"? ¿Puedes respaldar esto con estadísticas concretas? ¿Cuántos leíste? ¿Cuántos hay? ¿Cuántos carecían de la documentación adecuada? Si no tiene números, elimine palabras como "la mayoría" y reemplácelas con hechos reales basados en lo que realmente encontró. Además, escriba en mayúscula "I" cuando se refiera a usted mismo.

— S.Lott

@ S.Lott Perdón por la subjetiva "más". Soy un novato en la industria del software. Intento buscar documentos de los que había oído hablar durante la escuela universitaria (como UML Diagram, Flow Chart, Brief Design Doc, Detaled Design Doc, etc.) para los proyectos mencionados tanto en el sitio web del proyecto como en el repositorio de códigos, pero sin suerte, solo para encontrar alguna guía de usuario doc. ¿Me puede enseñar alguna forma común de buscar en sus documentos de diseño / archivo?

— TomCaps

1

Por favor, elimine "Muchos". Eso es tan incorrecto como la mayoría. por favor, actualice la pregunta a la lista específicamente los proyectos de código abierto específicas que carecen específicamente la documentación específica que desea ver. Por favor sea preciso y específico. Por favor, no seas subjetivo y vago.

— S.Lott

Sospecho que la razón por la que ASP.NET MVC no incluye diagramas UML es porque Visual Studio puede crearlos desde el código fuente.

— user16764

55

Estás operando bajo la falsa suposición de que "emprendedor" es algo bueno. Lo que aprendiste en la universidad sobre el diseño son mentiras: UML no tiene absolutamente ningún valor. Al crear un proyecto, todo lo que necesita es una idea general de lo que debe hacer y una disposición a tirarlo si lo hace mal la primera vez. Para un proyecto existente, solo rozar el encabezado principal suele ser suficiente para tener una buena idea sobre el diseño del proyecto.

— o11c

10

¿Por qué un proyecto de código abierto puede tener éxito si el desarrollador recién llegado no tiene un documento de arquitectura / diseño para leer?

Se asume invariablemente que sabes lo que estás haciendo y tienes una comprensión razonablemente íntima de lo que vas a ver (y lo que esperas).

Si examina el código PHP del marco de Symfony, por ejemplo, se espera que ya sepa sobre la inyección de dependencia, los eventos, el modelo / vista / patrón del controlador, etc.

Del mismo modo, si se sumerge en el código C del kernel de Linux, se supone que será realmente competente en modularidad, señales, procesos, subprocesos y demás. También se espera que tenga la habilidad de comer hexadecimal todo el día y excavar a través de vertederos con una pala gigante.

Los encargados del mantenimiento no pasarán por la molestia de documentar la arquitectura porque es una cuestión de hecho. En ocasiones, encontrará un resumen de lo que se encuentra en el árbol de origen. Sin embargo, más típicamente, la forma en que se organiza el árbol fuente hace que las cosas se expliquen por sí mismas.

En resumen, si carece de alguna de las habilidades que los encargados del mantenimiento esperarán que usted conozca para cuando eche un vistazo a su código, probablemente esté investigando cosas que están muy por encima de su nivel salarial. Familiarícese primero con los conceptos: ¿cuál es el modelo MVC? ¿Qué es la inyección de dependencia? Etc. Luego bucear.

— Denis de Bernardy
fuente

1

Sin embargo, si observa las listas de correo, el kernel de Linux tiene una extensa discusión sobre la arquitectura cada vez que alguien tiene un problema o desea cambiar algo. También hay bastantes documentos escritos al respecto, aunque no en el árbol de fuentes del núcleo.

— edA-qa mort-ora-y

17

La mayoría de los proyectos exitosos de código abierto tuvieron éxito porque, ante todo, el programa fue impresionante o hizo algo que ningún otro programa podía hacer en ese momento. Eso no significa necesariamente que la fuente esté bien documentada, ya que los programadores que comenzaron el proyecto para comenzar conocen el código lo suficientemente bien como para no necesitarlo. Es una realidad desafortunada que los proyectos de código abierto no tengan que estar bien documentados. Tiene que ser un buen programa o ser un programa mediocre pero bien documentado para que los programadores expresen interés en él.

— Neil
fuente

En mi empresa, es un procedimiento obligatorio que los desarrolladores deben proporcionar un documento de diseño detallado antes de ser aprobado, escribir cualquier código en un proyecto. ¿Es este procedimiento anormal para un proyecto de código abierto?

— TomCaps

55

@TomCaps creo que la mayor razón por la que tan pocos proyectos de software libre tienen una amplia documentación es bastante simple: si su escritura de un pequeño programa para resolver una necesidad que se tiene, lo más probable es que, dado que el desarrollador que no también necesita documentación, van a querer pasar su tiempo mejorando el programa en lugar de escribir documentación que no se garantiza que sea útil para nadie (¿qué pasa si el proyecto nunca es utilizado por nadie excepto el desarrollador?). No es la mejor práctica, pero muchos proyectos de software libre tienen poco tiempo de desarrollo.

— Jeff Welling

55

@ TomCaps: este procedimiento es anormal para la mayoría de las empresas que conozco ...

— Treb

1

La mayoría de los proyectos de código abierto no son empresas. Estás pensando en lo que sucede cuando hay un proyecto que me pagan para construir, con un plazo y un presupuesto. Si tienes un montón de personas codificando para satisfacer una necesidad que tienen o por diversión y no hay presupuesto o cliente, no tienes ese tipo de cosas.

— Elin

1

@ TomCaps: cualquiera que escriba software de código abierto puede hacer exactamente lo que quiera. Algunos proyectos (por ejemplo, la familia Apache) tienen reglas y pautas para cualquiera que cometa código y, a veces, esto incluye estándares de doumentation, etc. También cuestionaría el valor de un "documento de diseño detallado", ya que invariablemente lo encerrará en un diseño físico que (en mi experiencia personal) suele ser subóptima. Una descripción detallada de "qué" debe hacer el programa deja al desarrollador libre para optimizar la implementación y aplicar estrategias creativas a la solución.

— James Anderson el

12

Debido a que los desarrolladores de código abierto generalmente tienen talento y también eligen proyectos en su área de experiencia, ya tienen "documentación" dentro de sus cráneos. Con poca exageración, solo se necesita documentación exhaustiva si no tiene alguno de estos: o)

Para ser honesto, realmente no leo "documentación" cuando enfrento código base desconocido. ¡Una introducción rápida, tal vez algunos bocetos conceptuales y directamente al código! Experimente, pruebe pequeños cambios. Funciona perfectamente para un código bien diseñado. Si me enfrento a un desastre horrible, entonces la mejor manera de aprenderlos es refactorizar poco a poco para mejorar la claridad (idealmente con la ayuda de pruebas unitarias).

Una razón adicional podría ser la simple raíz del diseño orgánico de estos proyectos. La arquitectura es, entonces, una visión más evolucionada en la mente de los desarrolladores que una entidad declarada "documentada".

— Mar
fuente

8

La razón por la que tales documentos a menudo no existen es bastante simple: a los programadores les gusta programar, no escribir documentación. Especialmente con proyectos de código abierto, que los desarrolladores a menudo contribuyen durante su tiempo libre / libre.

Básicamente, escribir documentación no es divertido. Y si no les pagan, ¿quién quiere pasar su tiempo libre haciendo algo que no sea divertido?

— Gran maestro B
fuente

Algunos grandes proyectos de código abierto (GCC, el kernel de Linux, Firefox, Qt, ...) tienen a la mayoría (o una parte significativa) de sus contribuyentes remunerados para trabajar (a tiempo completo o medio tiempo) en el proyecto. Entonces, incluso cuando se paga por el software libre, no escriben mucha documentación

— Basile Starynkevitch