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

Debido a que es un esfuerzo adicional crear y mantener un documento de este tipo, y muchas personas no entienden los beneficios asociados.

Muchos programadores no son buenos escritores técnicos (aunque muchos lo son); rara vez escriben documentos estrictamente para el consumo humano, por lo tanto no tienen práctica y no les gusta hacerlo. Escribir una descripción general del código requiere tiempo que no puede gastar en codificación, y el beneficio initial para un proyecto siempre es mayor si puede decir "admitimos las tres variantes de codificación" en lugar de "realmente tenemos ¡Explicaciones claras de nuestro código! La noción de que tal documento atraerá a más desarrolladores para que a la larga se escriba más código no es exactamente extranjera 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 ahora mismo , sin duda lograremos que esto se haga.

Un documento de resumen de código también puede hacer que las personas se sientan a la defensiva; es difícil describir las decisiones de nivel superior sin sentir la necesidad de justificarlas, y muy a menudo las personas toman decisiones sin una razón que "suena lo suficientemente buena" cuando se escribe propia. También hay un efecto relacionado con el mencionado: dado que actualizar el texto para que se adapte a los cambios en el código provoca un esfuerzo adicional, esto puede desalentar los 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 se enfrentan a una dura competencia. La mayoría de estos proyectos no comienzan con hombros grandes, comienzan con una idea brillante, a menudo una idea brillante de un solo hombre.

Como tales, no pueden costear el tiempo y los costos de contratar doctores humanos, incluso si se ofrecieran a cooperar de forma gratuita. Un proyecto documentado, de hecho, generalmente ha pasado por varias iteraciones iniciales primero. A menudo comienza con 1-3, tal vez 5 chicos escriben su idea de novela y la muestran al mundo como una prueba de concepto. Si la idea es buena, entonces los "seguidores" pueden agregar, tienden 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 planear expansiones, etc. También podría convertirse en el "evangelista" del proyecto y, a veces, también en el "gerente del proyecto" (otras veces son personas diferentes). Ese es un paso necesario para llevar a cabo el proyecto, desde la prueba de concepto hasta una realidad establecida en la industria.

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

Un proyecto dinámico y en crecimiento se desaceleraría y la documentación se retrasaría mucho con respecto al código, mientras que se está mejorando mucho para implementar traducciones, opciones, administradores de enchufes ...

Lo que suele ocurrir es:

1. Se hace un breve documento introductorio, sobre qué es el proyecto y hacia dónde va (el famoso "mapa de ruta").
2. Si es posible, se desarrolla una API y esa se elige como "código documentado" en la mayor parte del código subyacente.
3. Especialmente la API, pero también el otro código se reformatea y se agregan comentarios "PHPdoc" / "Javadoc", etc. Ofrecen un compromiso decente entre el tiempo gastado y la recompensa: incluso un programador modesto generalmente sabe cómo escribir una sola línea que describe 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 retraso en el desarrollo.
4. Más 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 montón de conocimiento surja y se consolide lentamente por las preguntas frecuentes y los CÓMO de la comunidad (lea: no tiene en cuenta al equipo de desarrolladores).
5. En proyectos realmente grandes, también se produce un wiki. Digo "proyectos grandes" porque a menudo son aquellos con suficientes seguidores para crear un wiki (un desarrollador) y luego lo llenan más allá de los "huesos desnudos" (la comunidad lo hace).

Los documentos generales como los que 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 redacción técnica y, como resultado, tienen una buena documentación de 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 es relativamente autoexplicativo. 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 entiendes uno, entenderás el diseño de otros proyectos utilizando el mismo diseño.

Para cambiar una línea de código necesita una comprensión limitada del código circundante. Nunca debe tener que entender el código base completo para hacerlo. Si tiene una idea razonable del tipo de función que está dañada, a menudo es posible navegar 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 entiende cuál es el comportamiento esperado del método, debe poder realizar cambios correctivos o extensiones a la funcionalidad.

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

Consulte mi artículo Agregar SHA-2 a tinyca para ver un ejemplo de cómo se pueden hacer dichos cambios. Tengo un conocimiento muy limitado del código utilizado para generar la interfaz.

  

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

Hay un excelente libro llamado La arquitectura de las aplicaciones de código abierto que proporciona descripciones detalladas de una variedad de perfiles Proyectos de software de código abierto. Sin embargo, no estoy seguro de si cumple exactamente el rol que está imaginando, porque creo que su audiencia principal está destinada a ser desarrolladores que buscan patrones a seguir cuando crean sus propias aplicaciones, no nuevos contribuyentes a los proyectos que aparecen 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 al día. Cuanto más voluminosa sea la documentación, más tardará. 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 tardar en 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? ¿Es el costo mantener la documentación actualizada cada vez que los cambios de código valgan las contribuciones de desarrolladores adicionales que pueden o no aportar?

El código de envío gana. Reducir la cantidad de esfuerzo en cosas que no sean el código de envío puede hacer que el código se envíe con más frecuencia, y es más probable que se envíe antes de que se agoten 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 puede ser mucho más alto que agregar un documentor. Y, como se señaló, la documentación puede aumentar la inversión en el proyecto (al facilitar la incorporación de nuevos programadores).

Sin embargo, nada se vende como un éxito: un proyecto que no funciona o no hace nada interesante tampoco 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 describen 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 desean y hacer que su base de código tenga valor.

Algunas veces, hacer las cosas más difíciles hace que aquellos que hacen la tarea mejor. Ya sea debido a un mayor grado de compromiso con el proyecto (pasar horas y horas aprendiendo la arquitectura), o debido a un sesgo de habilidades (si ya es un experto en tecnología relacionada, alcanzar la velocidad será más rápido, por lo que la barrera de la falta) 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 el código base. Escribir dicha documentación no ayuda a ellos a entender mucho el código base, 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: falta de documentación que ya dice lo que el desarrollador rara vez pica.

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

Solo para nombrar a uno bastante popular: bluez. Buena suerte para encontrar un buen tutorial, además de buscar dispositivos cercanos.