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

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?

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.

¿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).

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.

¿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í).

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.

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.