¿Por qué algunas bibliotecas de openouce carecen de comentarios?

8

No sé si esto le sucede a la mayoría de las bibliotecas de código abierto, pero muchas de las que conozco y utilizo (por ejemplo, OpenSSL, Webkit, ...) todas carecen de comentarios o contienen muy pocos comentarios.

Sin mencionar sus muy pocos documentos, es difícil leer su código fuente. Difícilmente podemos entender qué significa una variable miembro o qué hace esta función. Esto parece estar en contra de la práctica estándar de codificación

¿Porqué es eso? ¿Cómo pueden las personas colaborar con estos de código abierto con muy pocos comentarios?

onmyway133
fuente
2
No son específicamente los comentarios importantes, pero la legibilidad del código. Pero supongo que querías decir eso, así que te sugiero que reformules tu pregunta. Aquí había una pregunta relacionada (no un duplicado). programmers.stackexchange.com/questions/185923/…
Doc Brown
Además del comentario hecho por @DocBrown arriba, no desea asegurarse de que su código también esté bien estructurado (por ejemplo, pasos coherentes en las declaraciones). El código legible y bien estructurado elimina la necesidad de poner miles de millones de líneas de comentarios innecesariamente. Y las bibliotecas / proyectos de OpenSource suelen ser para usuarios intermedios y avanzados de lenguaje de programación / scripting. Si alguien acaba de aprender a escribir "Hello World" y se mete en ellos, probablemente ningún comentario o código sea significativo para ellos. Los comentarios son buenos y necesarios, solo cuando piensas que va a ser ambiguo para un usuario normal.
hagubear 01 de
Tenga en cuenta que tener pocos comentarios no necesariamente significa que el código debe ser difícil de leer. Idealmente, el código debería ser legible sin comentarios. Ver, por ejemplo, programmers.stackexchange.com/questions/1/…
sleske

Respuestas:

15

Escribir código fuente es divertido.

Escribir documentación y comentar código es menos divertido.

Cuando un desarrollador trabaja en una empresa que aplica buenos comentarios y documentación, no hay otra opción: o bien este desarrollador los escribe o corre el riesgo de ser despedido.

Cuando un desarrollador contribuye a un proyecto de código abierto, lo hace de forma gratuita, y especialmente por diversión. No hay nadie que obligue a este desarrollador a hacer cosas que no está dispuesto a hacer, como escribir documentación y comentarios.

Es por eso que muchos proyectos de código abierto carecen de una amplia documentación y comentarios.


¿Cómo puede la gente contribuir a proyectos de código abierto sin documentación ni comentarios?

  • Si el código fuente es de alta calidad, los comentarios no son necesarios demasiado. Los comentarios de las interfaces públicas y la documentación son especialmente útiles para los consumidores del proyecto, es decir, los desarrolladores que simplemente usan bibliotecas, no contribuyen a ellos.

  • No hay factor de productividad involucrado. Estoy trabajando en una empresa donde la base de código real no tiene pruebas unitarias, ni documentación, ni comentarios. Paso mucho tiempo averiguando qué está haciendo un método 600-LOC o codificando cosas que ya están hechas, pero que no se pueden descubrir debido a la falta de documentación, por lo que la mayoría de las veces, simplemente estoy desperdiciando el dinero de la compañía en lugar de hacer algo valioso.

    Por otro lado, para un proyecto de código abierto, no importa si uno de los contribuyentes desperdició una semana debido a la falta de documentación o comentarios adecuados. Lo peor que puede pasar es que este contribuyente abandone el proyecto.

    Descubrir el código sin comentarios o documentación puede incluso ser un desafío, es decir, atraer a algunos contribuyentes, en lugar de desalentarlos.

  • En proyectos empresariales, no es inusual que un desarrollador se vea obligado a trabajar en todos los aspectos de un producto y, pocos años después, tenga que conocer casi todo el sistema. En un proyecto de código abierto, nadie te obliga a saberlo todo. Simplemente puede contribuir a una pequeña parte y tener un excelente conocimiento de esta parte, sin necesidad de documentación.

Arseni Mourzenko
fuente
3
"Cuando un desarrollador contribuye a un proyecto de código abierto, lo hace de forma gratuita, y especialmente por diversión". Existen numerosos proyectos de código abierto con los que se les paga a las personas por trabajar. Dudo que los ingenieros de IBM que trabajan con el kernel de Linux lo hagan de forma gratuita; Creo que es una apuesta segura que a las personas que desarrollaron MySQL se les pagó por hacerlo; y así. No estoy diciendo que esto sea lo más común o incluso particularmente común, pero ciertamente tampoco es justo decir que solo porque el código se hará público, al programador no se le paga por hacer el trabajo. Personalizaciones aún más.
un CVn
2
@ MichaelKjörling: +1. De hecho, me he olvidado de este caso. Por cierto, sería interesante comparar los comentarios en código fuente abierto donde se pagaba a los desarrolladores frente a los comentarios en código fuente gratuito.
Arseni Mourzenko 01 de
2

Muchas rasones.

  • Escribir documentación no es divertido, y para muchos proyectos, la base de usuarios es el equipo de programación; todos saben de qué se trata el código, por lo que la documentación no se ve realmente como un aspecto importante del proyecto.
  • La documentación puede (y será) desactualizada, y la documentación desactualizada es peor que ninguna. Esto significa que la documentación es una responsabilidad adicional y puede afectar la flexibilidad de su base de código (más documentación significa cualquier cambio que tendrá que actualizar el código y la documentación). Especialmente para proyectos de código abierto muy específicos, este es en realidad un argumento válido para apuntar a una documentación mínima y, en su lugar, escribir código legible.
  • La economía del software de código abierto es diferente. Si bien es bueno tener colaboradores en su proyecto, muchos proyectos son proyectos de tipo scratch-an-itch que el autor ha escrito para resolver un problema en particular y luego los descartó, tal como están. Dado que básicamente se está comiendo las migas de pan de otra persona, la actitud es que no está en condiciones de exigir nada, y mucho menos documentación.
tdammers
fuente
2

¿Cómo pueden las personas colaborar con estos código abierto con muy pocos comentarios?

Supongo que usted quiso decir "¿Cómo pueden las personas colaborar con este código de código abierto que es difícil de leer?" Bueno, supongo que un proyecto de código abierto con código incorrecto simplemente tendrá menos contribuyentes de lo que podría haber tenido con un buen código. Pero no olvide que la legibilidad del código siempre está en el ojo del espectador, y la mayoría del código fuente abierto no es tan malo que no pueda entender al menos un poco o las intenciones de algunas funciones y clases.

A menudo, cuando desea contribuir con algo a un proyecto de código abierto, no necesita comprender todo, solo las partes en las que desea agregar una característica específica. Entonces, si un desarrollador necesita una característica faltante, probablemente morderá la bala, identificará las partes que necesita cambiar, "decodificará" esas partes mentalmente y agregará las nuevas características allí. Si es bueno, también intentará revisar y refactorizar las partes "decodificadas", pero supongo que en la práctica esto ocurrirá muy raramente.

Doc Brown
fuente
1
hmm, no estoy tan seguro sobre el mal código que significa menos contribuyentes. El número de contribuyentes tanto o más que ver con la estructura y el tipo del proyecto como con el código que contiene. Hay un código muy bueno con solo una o dos personas involucradas, que está destinado a un nicho pequeño, y cosas malas que hacen que miles de personas lo bloqueen con poca supervisión o supervisión por parte de personas que no son muy buenos programadores (piense en todos esos juegos y cosas que atraen a los escolares).
Jwenting 01 de
1
Estoy a favor de "menos contribuyentes que podría haber tenido ".
LSerni 01 de
@Iserni: sí, supongo que pienso similar al respecto, cambié mi respuesta en consecuencia
Doc Brown
Estoy de acuerdo con @jwenting. ¿Alguien ha mirado bajo el capó de Wordpress últimamente?
Radu Murzea 01 de