La lettura di javadoc è preferibile alla lettura del codice sorgente per familiarizzare con una libreria?

La raccomandazione è probabilmente sulla programmazione di un'interfaccia piuttosto che dell'implementazione .

Certo, se hai accesso al codice, non c'è nulla che ti impedisca di guardare all'implementazione per capire come funziona . Ma devi sempre assicurarti che in che modo non influenzi il consumo dell'API.

Quando consumi un'API stai lavorando contro un'astrazione. Cerca di interessarti solo con quali offerte dell'API (il contratto) e non il come (l'implementazione).

Questo perché non vi è alcuna garanzia che l'implementazione di un'API non cambierà drasticamente da una versione all'altra, anche se il contratto è rimasto invariato.

A parte la differenza tra l'interfaccia e l'implementazione, già spiegata nella precedente risposta , c'è un altro aspetto importante: complessità .

I sistemi di vita reale sono solitamente complessi. Se inizi a leggere il codice di una classe, scoprirai che dovresti anche leggere il codice di un'altra classe, poi un'altra, ecc. Poche ore dopo, sarai semplicemente perso in tutta la complessità e non ricorderà chi chiama cosa e in quali casi.

Quando si utilizzano solo i commenti dell'interfaccia, si riduce tutta questa complessità. Potrebbe essere che sotto il cofano, tutto è semplice. Oppure potrebbe essere che sotto il cofano, dozzine o centinaia di classi si interagiscono a vicenda, rendendo praticamente impossibile mantenere l'intera immagine nella tua testa.

Puoi fare un esperimento.

• Trova una parte in OpenCV che ti interessa. Leggi la documentazione dell'interfaccia. Quanto tempo ci vuole per essere in grado di cogliere le basi e utilizzare efficacemente la libreria?

• Ora guarda l'implementazione . Quante classi sono chiamate direttamente dall'interfaccia? Quante classi vengono chiamate da ciascuna di queste classi? Quante linee di codice ci sono? Quanti metodi? Quanto ci vorrà per esplorare tutto questo codice sorgente prima di avere un eccesso di stack nel cervello?

Is there a reason why, or a case when reading only the javadoc is the best thing to do?

Anche se sei del tutto corretto sul fatto che JavaDoc sia scaduto o non aggiornato, tende ad essere in un formato migliore per la lettura all'ingrosso rispetto al codice in un IDE. E ancora più importante, è in linguaggio naturale. Questo è importante per due casi:

1. Persone non abituate a leggere il codice. Ad esempio, gli studenti universitari sono più spesso meglio serviti leggendo descrizioni di funzioni in linguaggio naturale che cercando di capire il codice che stanno imparando.
2. Le persone che non usano l'inglese (o le lingue che usano almeno alfabeti fonetici) come lingua principale. Poiché JavaDoc può lavorare con caratteri che gli identificatori non possono, può fornire una descrizione migliore di ciò che sta accadendo a quegli utenti. In particolare, JavaDoc sembra avere anche alcune capacità di localizzare la documentazione per te .

Detto questo, sono un credente abbastanza strong nel codice leggibile. Per gli sviluppatori esperti, mi aspetto che leggere il codice sia un approccio migliore quasi sempre se questa opzione è disponibile.