¿Leer javadoc es preferible a leer el código fuente para familiarizarse con una biblioteca?

Acabo de encontrar lo siguiente en un manual de laboratorio en la universidad:

Es necesario estudiar las interfaces de las clases generando el javadoc para ellas para que sepa qué operaciones se proporcionan (siéntase libre de mirar el código, pero cuando use el código de otra persona, como aquí, debe trabajar desde el javadoc en lugar de el código siempre que sea posible).

No entiendo por qué este es el caso; ya que el javadoc podría estar desactualizado o describir mal la función del código. ¿Seguramente mirar el código fuente y leer los comentarios de javadoc es lo mejor?

¿Hay alguna razón por la cual, o un caso cuando leer solo el javadoc es lo mejor que se puede hacer?

source-code comments javadocs

— Todd Davies
fuente

En la mayoría de los casos, no tendrá la oportunidad de poder leer y comprender todo el código que necesitaría. También puede ser no obvio del código cómo se manejan los casos extremos.

— raptortech97

esto se ha preguntado y contestado muchas veces antes, empezando por primera pregunta en este sitio - “Los comentarios son un olor código” y múltiples cuestiones vinculadas a ella

— mosquito

Respuestas:

La recomendación probablemente sea sobre la programación en una interfaz en lugar de la implementación .

Claro, si tiene acceso al código, entonces no hay nada que le impida mirar la implementación para comprender cómo funciona. Pero siempre debe asegurarse de que el cómo no influya en su consumo de la API.

Cuando consume una API, está trabajando en contra de una abstracción. Intente preocuparse solo por lo que ofrece la API (el contrato) y no por el cómo (la implementación).

Esto se debe a que no hay garantía de que la implementación de una API no cambie drásticamente de una versión a la siguiente, incluso si el contrato no ha cambiado.

— MetaFight
fuente

Una de las mayores omisiones en una gran cantidad de documentación de la clase es una especificación clara de qué aspectos de los comportamientos aparentes de una clase pueden ser legítimamente confiables para los consumidores (y no deben cambiar en futuras versiones de la clase), y qué comportamientos pueden ser legítimamente cambiado y por lo tanto no puede confiarse legítimamente en él. Por ejemplo, si bien es costoso para una colección de mapeo proporcionar un orden de enumeración garantizado después de que se hayan eliminado los elementos, es barato garantizar que, siempre que no se hayan eliminado, los elementos se enumerarán en el orden en que se agregaron.

— supercat

Hay muchos casos en que el código puede necesitar una para construir una colección de mapeo a partir de una secuencia de elementos y luego procesar elementos en la secuencia original. Si la colección garantiza que los artículos se enumerarán en la secuencia en que se agregaron, la secuencia original puede abandonarse de manera segura, pero en ausencia de dicha garantía, debe conservarse. Documentar un comportamiento que la clase cumpliría "naturalmente" no le costaría nada a la implementación, pero habría hecho que la clase fuera más útil.

— supercat

@supercat: Sin embargo, eso restringe los ajustes / reescrituras posteriores de la clase. Lo que significa que cualquier decisión desafortunada nunca puede ser corregida.

— Deduplicador

@Dupuplicator: hay una compensación; la pregunta que debe hacerse es si vale la pena renunciar a un beneficio potencial para los consumidores a fin de facilitar ciertos tipos de posibles cambios de implementación. Sugeriría que el principio de YAGNI favorecería dar a los consumidores los beneficios a menos que uno realmente pueda articular los tipos de cambios que uno quisiera hacer, y no sería capaz de acomodar eficientemente dichos cambios sin negarles a los consumidores los beneficios. Alternativamente, uno podría tener uno AddOnlyDictionaryque promete mantener el orden de inserción y ofrece ...

— supercat

... seguridad de subprocesos de un lector y múltiples lectores, o piense que si se pudieran necesitar otros tipos de diccionario, podrían derivarse Dictionaryy las personas podrían migrar hacia el nuevo cuando escriben código que no necesita el comportamiento anterior. Tenga en cuenta que la capacidad de mantener el orden de adición generalmente no es relevante para el código que recibe un Dictionarymensaje desde otro lugar (ya que un diccionario recibido desde otro lugar puede haber eliminado un elemento en algún momento), pero solo para el código que crea instancias a través del constructor. En cualquier caso, si un diccionario no aceptará una garantía Además orden ...

— supercat

Además de la diferencia entre la interfaz y la implementación, ya explicada en la respuesta anterior , hay otro aspecto importante: la complejidad .

Los sistemas de la vida real suelen ser complejos. Si comienza a leer el código de una clase, encontrará que también debe ir y leer el código de otra clase, luego otra, etc. Algunas horas después, simplemente se perderá en toda la complejidad y No recordaré quién llama qué y en qué casos.

Cuando usa solo los comentarios de la interfaz, mitiga toda esta complejidad. Puede ser que debajo del capó, todo sea simple. O puede ser que bajo el capó, docenas o cientos de clases interactúen entre sí, lo que hace prácticamente imposible mantener toda la imagen en su cabeza.

Puedes hacer un experimento.

Encuentre una parte en OpenCV que le interese. Lea la documentación de la interfaz. ¿Cuánto tiempo se tarda en poder comprender los conceptos básicos y utilizar eficazmente la biblioteca?
Ahora mire la implementación . ¿Cuántas clases son llamadas directamente por la interfaz? ¿Cuántas clases convoca cada una de esas clases? ¿Cuántas líneas de código hay? Cuantos metodos ¿Cuánto tiempo le tomaría explorar todo este código fuente antes de tener un desbordamiento de pila en su cerebro?

— Arseni Mourzenko
fuente

Principalmente, esa debe ser la razón por la cual las actualizaciones tardan tanto, y por qué los agujeros de seguridad pueden pasar tanto tiempo sin ser descubiertos, porque es muy difícil analizar la implementación de un programa sofisticado. Intenté mirar la fuente de Java de los primeros dos semestres de un curso de programación de Java. Creo que no había una clase que no llamara al menos a otras 2 clases, y esas clases a las que llamaban también llamaban a cualquier número de clases. Nunca pude seguir un rastro de código hasta su finalización final. Sería simplemente tomar demasiado tiempo, y que era demasiado difícil seguir la pista de donde yo estaba en und

— Progfram

¿Hay alguna razón por la cual, o un caso cuando leer solo el javadoc es lo mejor que se puede hacer?

Si bien tiene toda la razón de que JavaDoc puede estar desactualizado o ser malo, tiende a estar en un mejor formato para leer al por mayor que el código en un IDE. Y lo más importante, está en lenguaje natural. Eso es importante para dos casos:

Personas no acostumbradas a leer códigos. Los estudiantes universitarios, por ejemplo, son más propensos a leer mejor las descripciones de las funciones en lenguaje natural que tratar de comprender el código que están aprendiendo.
Las personas que no usan inglés (o idiomas que usan alfabetos fonéticos al menos) como su idioma principal. Dado que JavaDoc puede trabajar con caracteres que los identificadores no pueden, puede proporcionar mejores descripciones de lo que está sucediendo a esos usuarios. JavaDoc en particular parece incluso tener alguna capacidad para localizar la documentación por usted .

Dicho esto, creo bastante en el código legible. Para los desarrolladores experimentados, espero que leer el código sea un mejor enfoque casi todo el tiempo si esa opción está disponible.

— Telastyn
fuente