A leitura do javadoc é preferível à leitura do código-fonte para se familiarizar com uma biblioteca?

Acabei de encontrar o seguinte em um manual de laboratório na universidade:

Você precisa estudar as interfaces das classes gerando o javadoc para elas para saber quais operações são fornecidas (fique à vontade para olhar o código, mas ao usar o código de outra pessoa, como aqui, você deve trabalhar no javadoc em vez de o código sempre que possível).

Não entendo por que esse é o caso; já que o javadoc pode estar desatualizado ou pode descrever mal a função do código. Certamente olhando o código fonte e lendo os comentários do javadoc é melhor?

Existe uma razão para isso, ou um caso em que ler apenas o javadoc é a melhor coisa a fazer?

source-code comments javadocs

— Todd Davies
fonte

Na maioria dos casos, você não terá a chance de ler e entender todo o código necessário. Também pode não ser óbvio no código como os casos extremos são tratados.

— Raptortech97

isso tem sido feitas e respondidas muitas vezes antes, começando com primeira pergunta neste local - “Os comentários são um cheiro de código” e várias questões ligadas a ele

— mosquito

Respostas:

A recomendação é provavelmente sobre a programação para uma interface e não a implementação .

Claro, se você tem acesso ao código, não há nada que o impeça de olhar para a implementação para entender como ela funciona. Mas você deve sempre garantir que o modo como não influencie seu consumo da API.

Quando você está consumindo uma API, está trabalhando contra uma abstração. Tente se preocupar apenas com o que a API oferece (o contrato) e não com o modo (a implementação).

Isso ocorre porque não há garantia de que a implementação de uma API não mude drasticamente de uma versão para a seguinte, mesmo que o contrato permaneça inalterado.

— MetaFight
fonte

Uma das maiores omissões em muitos documentos de classe é uma especificação clara de quais aspectos dos comportamentos aparentes de uma classe podem ser legitimamente invocados pelos consumidores (e não devem ser alterados em versões futuras da classe) e quais comportamentos podem ser legitimamente alterada e, portanto, não pode ser legitimamente invocada. Por exemplo, enquanto é caro para uma coleção de mapeamento para fornecer qualquer ordem garantida de enumeração após quaisquer itens foram excluídos, é barato para garantir que, enquanto não tem itens têm sempre sido excluído, itens irá enumerar na ordem em que foram adicionados.

— Supercat 04/02

Há muitos casos em que o código pode precisar de um para criar uma coleção de mapeamento a partir de uma sequência de itens e processar itens posteriores na sequência original. Se a coleção garantir que os itens serão enumerados na sequência em que foram adicionados, a sequência original poderá ser abandonada com segurança, mas, na ausência de tal garantia, ela deverá ser mantida. Documentar um comportamento que a classe "naturalmente" obedeceria não custaria nada à implementação, mas teria tornado a classe mais útil.

— Supercat 04/02

@ supercat: Isso restringe posteriormente os ajustes / reescrições da classe. O que significa que qualquer decisão infeliz nunca pode ser corrigida.

— Deduplicator

@Duplicador: Há uma troca; a pergunta a ser feita é se vale a pena mencionar um benefício potencial para os consumidores, a fim de facilitar certos tipos de possíveis alterações na implementação. Eu sugeriria que o princípio YAGNI fosse a favor de dar aos consumidores os benefícios, a menos que alguém possa realmente articular os tipos de mudanças que gostaria de fazer, e não seria capaz de acomodar essas mudanças com eficiência, sem negar os benefícios aos consumidores. Como alternativa, alguém poderia ter um AddOnlyDictionaryque prometesse manter o pedido de inserção e oferece ... #

— 308

... segurança de threads de um leitor para vários leitores ou figura que, se forem necessários outros tipos de dicionário, eles podem ser derivados Dictionarye as pessoas podem migrar para o novo ao escrever código que não precisa do antigo comportamento. Observe que a capacidade de manter a ordem de adição geralmente não é relevante para o código que recebe um Dictionaryde outro lugar (já que um dicionário recebido de outro lugar pode ter um item excluído em algum momento), mas apenas para o código que cria instâncias por meio do construtor. De qualquer forma, se um dicionário não atender a uma garantia de pedido de adição ... #

— 686

Além da diferença entre a interface e a implementação, já explicada na resposta anterior , há outro aspecto importante: complexidade .

Os sistemas da vida real são geralmente complexos. Se você começar a ler o código de uma classe, verá que também deve ler o código de outra classe, depois de outra, etc. Algumas horas depois, você estará simplesmente perdido em toda a complexidade e não se lembrará de quem liga para quê e em que casos.

Quando você usa apenas os comentários da interface, reduz toda essa complexidade. Pode ser que, sob o capô, tudo seja simples. Ou pode ser que, sob o capô, dezenas ou centenas de classes interajam, tornando praticamente impossível manter toda a imagem em sua cabeça.

Você pode fazer um experimento.

Encontre uma peça no OpenCV que lhe interessa. Leia a documentação da interface. Quanto tempo leva para entender o básico e usar efetivamente a biblioteca?
Agora observe a implementação . Quantas classes são chamadas diretamente pela interface? Quantas classes são chamadas por cada uma dessas classes? Quantas linhas de código existem? Quantos métodos? Quanto tempo você levaria para explorar todo esse código-fonte antes de ter uma pilha cheia no seu cérebro?

— Arseni Mourzenko
fonte

Principalmente, é por isso que as atualizações demoram tanto e as falhas de segurança podem durar tanto tempo sem serem descobertas, porque é tão difícil examinar a implementação de um programa sofisticado. Tentei apenas examinar a fonte Java dos dois primeiros semestres de um curso de programação em Java. Eu acho que não havia uma classe que não chamasse pelo menos duas outras classes, e as classes que eles chamavam também chamavam qualquer número de classes. Eu nunca fui capaz de seguir uma trilha de código até sua conclusão final. Seria simplesmente levar muito tempo, e foi muito difícil manter o controle de onde eu estava no und

— Progfram

Existe uma razão para isso, ou um caso em que ler apenas o javadoc é a melhor coisa a fazer?

Embora você esteja totalmente certo de que o JavaDoc pode estar desatualizado ou ruim, ele tende a estar em um formato melhor para leitura por atacado do que código em um IDE. E o mais importante, é em linguagem natural. Isso é importante para dois casos:

Pessoas não acostumadas a ler código. Os estudantes universitários, por exemplo, provavelmente são mais bem atendidos lendo descrições de funções em linguagem natural do que tentando entender o código que eles estão no processo de aprendizado.
Pessoas que não usam o inglês (ou idiomas que usam pelo menos alfabetos fonéticos) como idioma principal. Como o JavaDoc pode trabalhar com caracteres que os identificadores não podem, ele pode fornecer melhores descrições do que está acontecendo com esses usuários. O JavaDoc, em particular, parece ter alguma capacidade de localizar a documentação para você .

Dito isto, acredito bastante em código legível. Para desenvolvedores experientes, espero que a leitura do código seja uma abordagem melhor quase o tempo todo, se essa opção estiver disponível.

— Telastyn
fonte