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
fonte
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.
fonte
AddOnlyDictionary
que prometesse manter o pedido de inserção e oferece ... #Dictionary
e 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 umDictionary
de 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 ... #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?
fonte
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:
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.
fonte