¿Por qué no hay descripciones generales de código para proyectos de código abierto? [cerrado]

60

Existen proyectos de código abierto muy complejos, y para algunos de ellos creo que podría hacer algunas contribuciones, y desearía poder hacerlo, pero la barrera de entrada es demasiado alta por una sola razón: para cambiar una línea de código a la vez. gran proyecto tienes que entenderlo todo.

No necesita leer todo el código (incluso si lo lee, no será suficiente) y comprender todo lo que hace cada línea y por qué, porque el código probablemente está modularizado y compartimentado, por lo que hay abstracciones en su lugar, pero incluso entonces necesita obtener una visión general del proyecto para poder saber dónde están los módulos, dónde se conecta un módulo con otro, qué hace exactamente cada módulo y por qué , y en qué directorios y archivos están sucediendo cada una de estas cosas.

Llamo a esta descripción general del código , como el nombre de una sección que los proyectos de código abierto podrían tener en el sitio web o en la documentación que explica su código a personas externas. Creo que beneficiaría a los contribuyentes potenciales , ya que podrían identificar lugares donde podrían construir, los codificadores primarios reales involucrados, ya que podrían, al escribir todo, reorganizar sus mentes y ayudar a los usuarios , como lo harían les ayudará a comprender y reportar mejor los errores que experimentan y tal vez incluso se conviertan en contribuyentes.

Pero aún así, nunca he visto una de estas "descripciones generales de código". ¿Por qué? ¿Hay cosas como estas y las extraño? ¿Cosas que hacen el mismo trabajo que estoy describiendo? ¿O es una idea completamente inútil, ya que todos, excepto yo, pueden entender proyectos con miles de líneas de código fácilmente?

fiatjaf
fuente
77
¿Te refieres a un documento de diseño? He visto el raro proyecto con una descripción de cada paquete, pero ya es una API.
monstruo de trinquete
14
¿Por qué? Debido a que hay pocos proyectos cuyos mantenedores desean invertir el esfuerzo de escribir y mantener documentación de alta calidad, y a menudo tampoco pueden comprender los beneficios.
Alex D
99
La documentación puede estar desactualizada o ser inexacta en relación con el comportamiento real. El código no puede. Entonces, la mayoría de los proyectos prefieren el código.
Paul Draper
55
También es fácil subestimar cuánto puede aprender sobre un proyecto si configura un temporizador de cocina durante 2 horas más o menos y Just Read It (tm).
Kos
43
Bienvenido al mundo impulsado por la comunidad: si no se hace, es porque no lo has hecho :)
mgarciaisaia

Respuestas:

60

Debido a que es un esfuerzo adicional crear y mantener dicho documento, y demasiadas personas no entienden los beneficios asociados.

Muchos programadores no son buenos escritores técnicos (aunque muchos lo son); rara vez escriben documentos estrictamente para consumo humano, por lo tanto no tienen práctica y no les gusta hacerlo. Escribir una descripción general del código lleva tiempo que no puede gastar en codificación, y el beneficio inicial de un proyecto siempre es mayor si puede decir "Admitimos las tres variantes de codificación" en lugar de "¡Tenemos explicaciones muy claras de nuestro código!" La noción de que dicho documento atraerá a más desarrolladores para que a la larga se escriba más código no es exactamente extraño para ellos, pero se percibe como una apuesta incierta; ¿Este texto realmente hará la diferencia entre enganchar a un colaborador o no? Si sigo codificando en este momento , Haz esto.

Un documento de descripción general del código también puede hacer que las personas se sientan a la defensiva; es difícil describir decisiones de alto nivel sin sentir la necesidad de justificarlas, y muy a menudo las personas toman decisiones sin una razón que "suena lo suficientemente buena" cuando en realidad se escriben por sí mismas. También hay un efecto relacionado con el mencionado anteriormente: dado que actualizar el texto para adaptarlo al código cambiante causa un esfuerzo adicional, esto puede desalentar cambios radicales en el código. A veces, esta estabilidad es algo bueno, pero si el código realmente necesita una reescritura de nivel medio, se convierte en una responsabilidad.

Kilian Foth
fuente
66
Bueno, parece que la respuesta es sí: gnunet.org/gnunet-source-overview
fiatjaf
55
Si quieres que exista, ofrécete como voluntario para escribirlo. El objetivo de los proyectos de código abierto es que las personas pueden y deben contribuir con lo que pueden, sujeto a que la comunidad acuerde que vale la pena integrarse.
keshlam
8
@keshlam - que tiene sentido si usted es ya un contribuyente al proyecto ... pero si usted es un contribuyente potencial que está tratando de tener una idea básica de cómo funciona el código, eres la peor persona posible escribir ese documento ...
Jon Story
13
@JonStory Tu punto es bueno, pero en la práctica he descubierto que a veces también sucede lo contrario. En algunos proyectos terminé escribiendo un montón de documentación basada en notas que hice mientras aprendía una base de código indocumentada. Era una mejor documentación porque tenía que comenzar en la API que podía ver y luego profundizar más y más. Los desarrolladores que habían escrito el código ya tenían un modelo del código en sus cabezas, por lo que tenían muchas suposiciones sobre lo que alguien ya sabría. La documentación de alguien nuevo en el proyecto puede ser una mejor documentación para alguien nuevo en el proyecto.
Joshua Taylor
66
@JonStory: si te estás involucrando en un proyecto menos que perfectamente documentado, tendrás que comenzar a resolver esto de todos modos. Hacer que sus notas formen parte del proyecto ayuda a salvar el trabajo de la próxima persona. (No sé si alguien usaría la presencia o ausencia de documentos como un factor decisivo sobre si contribuir). Simplemente mejorar los comentarios de javadoc (o equivalente) puede ser una forma valiosa de comenzar a contribuir. En serio, ese es el principio básico detrás del código abierto: si ve algo que debe hacerse, Hágalo en lugar de esperar a que alguien más lo haga.
keshlam
14

¿La seca y dura verdad?

La documentación no se realiza porque los proyectos pueden prescindir de ella.

Incluso los proyectos de código abierto a menudo enfrentan una dura competencia. La mayoría de estos proyectos no comienzan con grandes hombros, comienzan con una idea brillante, a menudo una idea brillante de un solo hombre.

Como tal, no pueden permitirse el tiempo y los costos de contratar documentadores humanos, incluso si se ofrecieron a cooperar de forma gratuita. Un proyecto documentado, de hecho, ha pasado por varias iteraciones iniciales primero. A menudo comienza con 1-3, tal vez 5 chicos escribiendo su idea novedosa y mostrándola al mundo como una prueba de concepto. Si la idea es buena, entonces los "seguidores" pueden agregar, tienden a comenzar a pedir extensiones, nuevas opciones, traducciones ... En este punto, el código sigue siendo un prototipo, generalmente con opciones y mensajes codificados.

No todos los proyectos de código abierto van más allá de esta fase, solo aquellos que rompen la "masa crítica" necesaria para atraer el interés público. Además, uno de los desarrolladores principiantes tiene que "pensar en grande y lejos" y planificar expansiones, etc. También podría convertirse en el "evangelista" del proyecto y, a veces, también en "gerente del proyecto" (otras veces son personas diferentes). Ese es un paso necesario para llevar el proyecto, desde la prueba de concepto hasta una realidad establecida en la industria.

Incluso entonces, el gerente del proyecto puede optar por no crear documentación.

Un proyecto dinámico y en crecimiento se ralentizaría y la documentación realmente quedaría rezagada con respecto al código mientras se mejora mucho, para implementar traducciones, opciones, enchufar administradores ...

Lo que suele pasar es:

  1. Se realiza un breve documento introductorio sobre el proyecto y hacia dónde se dirige (el famoso "mapa de ruta").
  2. Si es posible, se desarrolla una API y esa se elige como "código documentado" sobre la mayor parte del código subyacente.
  3. Especialmente la API, pero también el otro código se reformatean y se agregan comentarios especiales "PHPdoc" / "Javadoc", etc. Ofrecen un compromiso decente entre el tiempo invertido y la recompensa: incluso un programador modesto generalmente sabe cómo escribir una línea describiendo sus funciones, los parámetros también se documentan "automáticamente" y todo está vinculado a su código correspondiente y, por lo tanto, evitan la documentación " Desincronización "y desarrollo rezagado detrás.
  4. Muy a menudo, se crea un foro. Es una poderosa red social donde los usuarios finales y los programadores pueden hablar entre sí (y entre sus pares, posiblemente en subforos "solo para desarrolladores"). Esto permite que un gran conocimiento emerja lentamente y se consolide por las preguntas frecuentes y los CÓMO realizados por la comunidad (léase: sin pesar en el equipo de desarrolladores).
  5. En proyectos realmente grandes, también se produce un wiki. Declaro "proyectos grandes" porque a menudo son aquellos con suficientes seguidores para crear un wiki (un desarrollador lo hace) y luego lo llenan más allá de los "huesos básicos" (la comunidad lo hace).
Dario Fumagalli
fuente
2
¡¡GUAU!! Vivimos (y trabajamos) en dos mundos totalmente diferentes. Donde sea que esté trabajando actualmente, salga de allí rápidamente y encuentre una compañía (hay muchas) donde se haga correctamente porque eso realmente le ahorra dinero. Nunca dejes que los gerentes / codificadores de vaqueros puntiagudos intenten decirte lo contrario.
Mawg
66
+1, estoy de acuerdo con casi todos sus puntos, la única afirmación que rechazo es que los parámetros se documenten "automáticamente" . Cuando pensamos en explicaciones en lugar de las meras restricciones de sintaxis / tipo, nada se "auto documenta"; un comentario generado en el estilo Devuelve la X. para un método getX no es una documentación útil, es solo un relleno sin ninguna información adicional.
O Mapper
3
@Mawg proporcionar buena documentación es una inversión, renuncia al tiempo del desarrollador a cambio de (con suerte) más contribuyentes en el futuro y algunos otros beneficios. Pero como muchos de su tipo, solo vale la pena si sabe que hay una buena posibilidad de que el proyecto tenga éxito, y la mayoría de los proyectos de software fracasan. Es importante tener en cuenta el sesgo de supervivencia cuando lamenta la falta de documentación en proyectos exitosos.
congusbongus
¿No es posible que esos proyectos fallen porque no documentan? Y por documento, me refiero a un plan, para que entiendas, en lugar de sentarte al teclado y golpear. Aquí está mi estimación para el ciclo de vida de un proyecto, todas las cifras +/- 5%. Material inicial (requisitos y casos de uso, arquitectura, diseño detallado) 50%, codificación del 10 al 15%, pruebas, el resto. "Si no puede planificar, planea fallar"
Mawg
6

Los documentos de descripción general como los que usted describe son raros incluso en proyectos comerciales. Requieren un esfuerzo extra con poco valor para los desarrolladores. Además, los desarrolladores tienden a no escribir documentación a menos que realmente lo necesiten. Algunos proyectos tienen la suerte de tener miembros que son buenos en la escritura técnica y, como resultado, tienen una buena documentación del usuario. La documentación del desarrollador, si existe, es poco probable que se actualice para reflejar los cambios en el código.

Cualquier proyecto bien organizado tendrá un árbol de directorios que se explica por sí mismo. Algunos proyectos documentarán esta jerarquía y / o las razones por las que se eligió. Muchos proyectos siguen diseños de código relativamente estándar, por lo que si comprende uno, comprenderá el diseño de otros proyectos que usan el mismo diseño.

Para cambiar una línea de código, necesita una comprensión limitada del código circundante. Nunca debería tener que entender todo el código base para hacerlo. Si tiene una idea razonable del tipo de función que no funciona, a menudo es posible navegar por la jerarquía de directorios con bastante rapidez.

Para cambiar una línea de código, debe comprender el método dentro del cual se encuentra la línea. Si comprende cuál es el comportamiento esperado del método, debería poder hacer cambios correctivos o extensiones a la funcionalidad.

Para los idiomas que proporcionan alcance, puede refactorizar los métodos de ámbito privado. En este caso, es posible que deba cambiar las personas que llaman, así como el método o métodos refactorizados. Esto requiere una comprensión más amplia, pero aún limitada, de la base del código.

Vea mi artículo Agregar SHA-2 a tinyca para ver un ejemplo de cómo se pueden hacer dichos cambios. Tengo una comprensión extremadamente limitada del código utilizado para generar la interfaz.

BillThor
fuente
1
El punto importante aquí no fue afirmar cuánto necesita saber sobre el código para realizar un cambio. Por supuesto, esto dependerá de muchas cosas, pero nunca necesitará comprender todo el código, ni una descripción general le dará esa comprensión, pero incluso para encontrar la línea de código que cambiará necesita un cierto conocimiento de La estructura general del proyecto.
fiatjaf
+1 No hay nada especial sobre el código abierto. En mis más de 10 años de experiencia trabajando en la industria, nunca he visto un documento general. Lo que generalmente sucede es que los empleadores esperan que el primer mes de su empleo tenga una productividad cero porque está estudiando la base de código. Los "resúmenes" generalmente se implementan como preguntas a sus compañeros de trabajo
slebetman
5

¿Hay cosas como estas y las extraño? ¿Cosas que hacen el mismo trabajo que estoy describiendo?

Hay un excelente libro llamado The Architecture of Open Source Applications que proporciona descripciones detalladas de una variedad de proyectos de software de código abierto de alto perfil. Sin embargo, no estoy seguro de si cumple exactamente el papel que está imaginando, porque creo que su audiencia principal está destinada a ser desarrolladores que buscan patrones a seguir al crear sus propias aplicaciones, no nuevos contribuyentes a los proyectos presentados en el libro. (aunque estoy seguro de que podría ser útil allí).

bjmc
fuente
esto se lee más como un comentario, vea Cómo responder
mosquito
44
No encuentro tu comentario constructivo. ¿Qué, específicamente, sientes que falta? Muchas de las otras respuestas aquí son largas especulaciones sobre posibles razones por las cuales los desarrolladores podrían no escribir documentación general. He vinculado a un ejemplo específico de buenos documentos de resumen.
bjmc
1
Siento que falta una respuesta a la pregunta formulada, "¿Por qué no hay descripciones generales de código para proyectos de código abierto?"
mosquito
3
Yo diría que no es posible para responder con precisión a la pregunta escrita cuando, de hecho, no son descripciones de código para algunos proyectos de código abierto. He editado mi respuesta para dejar en claro que estoy respondiendo por poco a una solicitud de ejemplos que el usuario puede haber perdido.
bjmc
1
La pregunta como está escrita pregunta "¿Hay cosas como estas y las extraño?" Esta respuesta responde definitivamente, apuntando a una colección existente de tales descripciones generales de código. Como tal, creo que es una excelente (y apropiada) respuesta a la pregunta.
Jim Garrison
4

Porque hay muchos más programadores de código abierto que escritores técnicos de código abierto.

La documentación requiere mantenimiento y tiempo para mantenerse actualizado. Cuanto más voluminosa sea la documentación, más se necesita. Y la documentación que no está sincronizada con el código es peor que inútil: engaña y oculta en lugar de revelar.

Una base de código bien documentada es mejor que una menos documentada, pero la documentación puede llevar fácilmente tanto tiempo como escribir el código en primer lugar. Entonces, su pregunta es, ¿es mejor tener una base de código bien documentada o una base de código que sea el doble de grande? ¿El costo de mantener actualizada la documentación cada vez que los cambios en el código valen la contribución de los desarrolladores adicionales que puede o no aportar?

El código de envío gana. Reducir la cantidad de esfuerzo que se dedica a otras cosas que no sean el código de envío puede hacer que el código se envíe con más frecuencia y sea más probable que se envíe antes de que se acaben los recursos.

Esto no significa que las cosas además del envío importen. La documentación agrega valor al proyecto, y con un proyecto lo suficientemente grande, el costo de interconexión de agregar otro desarrollador podría ser mucho mayor que agregar un documentador. Y, como se señaló, la documentación puede aumentar la inversión en el proyecto (facilitando la incorporación de nuevos programadores).

Sin embargo, nada se vende como el éxito: un proyecto que no funciona o hace algo interesante rara vez atrae a los desarrolladores.

La documentación de una base de código es una forma de meta-trabajo. Puede pasar mucho tiempo escribiendo documentos sofisticados que describan una base de código que no tiene mucho valor, o puede dedicar tiempo a hacer cosas que los consumidores de su base de código quieren y hacer que su base de código tenga valor.

A veces, hacer las cosas más difíciles hace que quienes hacen la tarea sean mejores. Ya sea debido a un mayor grado de compromiso con el proyecto (pasar horas y horas aprendiendo la arquitectura) o debido al sesgo de habilidades (si ya es un experto en tecnología relacionada, ponerse al día será más rápido, por lo que la barrera de la falta de dicha documentación es menos importante: por lo tanto, más expertos se unen al equipo y menos principiantes).

Finalmente, por las razones mencionadas anteriormente, es probable que los desarrolladores actuales sean expertos en la base del código. Escribir dicha documentación no les ayuda a comprender mucho la base del código, ya que ya tienen el conocimiento, solo ayuda a otros desarrolladores. Gran parte del desarrollo de código abierto se basa en "rascarse una picazón" que el desarrollador tiene con el código: la falta de documentación que ya dice lo que el desarrollador rara vez pica.

Yakk
fuente
La documentación de +1 "puede llevar tanto tiempo como escribir el código en primer lugar", ¡o más!
Marco
-1

Además de ser un esfuerzo adicional , algunos proyectos de código abierto están paralizando sus documentaciones a propósito, con el fin de obtener trabajos independientes para sus mantenedores (para implementar algo o realizar capacitaciones). No solo no tienen una descripción general del código, sino que su API y tutoriales son malos o les faltan muchas cosas.

Solo por nombrar uno bastante popular: bluez. Buena suerte para encontrar un buen tutorial, aparte de buscar dispositivos cercanos.

BЈовић
fuente
8
No importa cuántos ejemplos pueda enumerar para proyectos de código abierto mal documentados, en mi opinión, la afirmación de que "están paralizando sus documentaciones a propósito" debe estar respaldada por evidencia concluyente (e incluso entonces probablemente no se considere como un declaración general).
O Mapper
@ORMapper Comencemos con "Bluez - el mayor misterio de Linux" . Como la única biblioteca de Bluetooth para Linux, me resulta difícil creer que no sea documentación porque es un esfuerzo adicional. Demonios, hay doxygen, y ¿qué tan difícil es escribir tutoriales simples?
Bћовић
@ORMapper Luego está el kernel de Linux. Si le falta algo (como un controlador de kernel), si su empresa no cuenta con la experiencia, puede contratar a alguien o buscar un profesional independiente o una empresa que lo haga por usted. Por lo tanto, es de código abierto, pero tiene un precio
BЈовић
@ORMapper Luego están los proyectos de código abierto, con documentación en formato papel. Entonces compra un libro y no se le da otra documentación. ¿Esta documentación es paralizante o no?
Bћовић
2
Por lo que vale, he visto suficiente aprovechamiento de la documentación de mala calidad para al menos preguntarme si es intencional. Cuando los mismos grupos que ponen en línea la documentación a medias están más que felices de venderle un libro o una clase de capacitación, no se necesita mucho cinismo para llegar a esa conclusión.
cHao