Desabafo Documentação

De que linguagem está falando que não tem boa documentação? Você está sendo obrigado a trabalhar com ela? As que trabalhei até hoje são bem ricas em documentação.

No geral todas são assim um exemplo disso são os blogs e fórum que ajuda mais que a documentação.

São formas diferentes de conteúdo, a vantagem da documentação na linguagem é de tê-la no intellisense, não precisando sair da edição de código, e a documentação do site oficial abranger tudo que é possível. Cada conteúdo tem sua vantagem, logicamente blogs costumam facilitar mais por focar em caso específico, e forum pode responder exatamente o que uma pessoa perguntou.

A documentação de linguagens de programação não costumam ter o objetivo de ensinar, mas sim de ser referência quanto à sintaxe, classes, métodos, funções e afins. Algumas são mais didáticas que outras, mas poucas vão a fundo. Se você tentar estudar pela documentação, pode se decepcionar mesmo.

Abraço.

Exatamente, esse é ponto-chave, documentação é para servir de referencia para quem já está trabalhando, não é para ensinar, não é voltado para didática.

Prezados os caras que fazem uma nova biblioteca deveriam se preocupar como implementar para a linguagem crescer, fica muito abstrato eu falar faz um bolo com ovos e farinha existe mil maneiras de fazer e vários tipos de bolo, o problema que eles não exemplificam.

Nesse caso não é culpa da “linguagem”, mas de quem fornece a biblioteca. Antes de pagar por uma biblioteca verifique se tem boa documentação. Se é de graça ai já quer demais né, mas as mais consagradas geralmente tem ótima documentação por receberem investimento.

Pois é, a documentação geralmente apresenta os Componentes, e não explica como Combiná-los e usá-los em conjunto para obter uma determinada solução. Mas às vezes você encontra na Documentação alguns exemplos de como os projetistas esperam que você Combine os Componentes e o resultado que obterá.

Quando você quer uma Solução específica, tem que pesquisar na internet, e em blogs/fóruns eles vão te mostrar como Combinar os Componentes para gerar a Solução que você quer. Mas o que acontece se a Biblioteca for bem desconhecida? Aí você não consegue encontrar na internet algo que te atenda, e isso complica bastante sua vida.

Portanto, acredito que seria melhor se as Documentações tivessem várias Soluções prontas onde você pode pesquisar na Documentação a Solução que você precisa, e, ao encontrar você teria aquela “receita de bolo” mostrando quais Componentes usar e como Combiná-los; e os Componentes usados (as Classes, Interfaces, Métodos, etc.) teriam referência para as “receitas de bolo” nas quais eles são utilizados.

Isso mesmo Douglas, cara tão fácil criei uma classe nova com certeza eu tenho em mente algumas formas de utilização e como aplicar, acho que não custa eu fazer algumas aplicações para demostrar sua eficácia.

Concordo quando existe investimento para isso, mas custar custa, qualquer tempo é dinheiro.

Concordo quando existe investimento para isso, mas custar custa, qualquer tempo é dinheiro.

É verdade que custa, e bastante. Mas e quem for usar a biblioteca? Quanto tempo essa pessoa vai precisar gastar para entender como usá-la e como solucionar seus problemas com ela? Se a pessoa não entender direito ela pode até usar incorretamente e ter problemas! Ou seja, o custo para quem for aprender e usar a biblioteca pode acabar sendo bem maior do que o custo que haveria sobre quem poderia ter feito explicações e exemplos sobre como utilizar a biblioteca.

Nesse caso o custo é seu de gastar para entender, não de quem disponibilizou a biblioteca de graça. Logicamente ele já sabe utilizar para uso próprio.

Você pode solicitar suporte também dependendo do caso.

Mas afinal de que biblioteca por exemplo vocês estão reclamando?

Mas pensa bem, se a biblioteca é desenvolvida por um time, cada pessoa vai ter que explicar pra outra o que fez e como utilizar? Não é melhor criar e armazenar essas explicações? E se até quem fez acabar esquecendo como utilizar depois de alguns meses? E se o sistema for passado para outra empresa, vai ser necessário explicar a biblioteca pro novo time?

Num time bem dividido seguindo metodologia ágil não precisa disso, pela convivência no dia a dia naturalmente todos sabem o que o outro faz, basta conversar. Agora se o sujeito vai disponibilizar a biblioteca para uso externo, deveria ter documentação, se não tem é porque não pretendem ter retorno com isso, apenas cederam a biblioteca. Você como usuário deveria buscar outra biblioteca que tenha documentação.

E o que acontece um bom tempo depois que o sistema foi feito e surgiu o interesse de alterá-lo ou reutilizar partes dele? E se quem fez não se lembra bem de como funciona e como usar (isso já aconteceu muito comigo, principalmente quando o modo de usar é Complexo, envolvendo compor Objetos da maineira certa, registrar as coisas certas nos lugares certos, etc.)? E se as pessoas da equipe ágil que conheciam certas partes da biblioteca já saíram da Empresa?

Eu acho que no futuro o preço a pagar por não ter feito e armazenado exemplos e explicações sobre a biblioteca poderá ser - muitas vezes - maior que o custo de tê-los feito antes.

Só para ambientes que tem problemas com alta rotatividade de pessoal, tipo fábrica de software, ai sim tem que ficar documentando tudo, seguindo N padrões, N siglas, etc. Mas se por exemplo um mesmo time de 5 pessoas se mantiverem juntas por mais de 5 anos com uma ou duas perdas, isso é desnecessário.

E como eles vão fazer para reutilizar as bibliotecas que já criaram há muito tempo?

Quando você cria um conjunto de Classes para serem usadas juntas de uma forma relativamente complexa, você consegue se lembrar de como usar aquilo alguns meses (ou mesmo anos) depois? Sai mais rápido para você relembrar de como usar do que ter feito e armazenado explicações?

Os integrantes que já conhecem vão passando conhecimentos para o novo integrante, naturalmente no dia a dia.

Dificuldade em dar manutenção por não lembrar é desculpa para código mal feito.

O propósito da documentação de uma linguagem não é ensinar a programar. É como o @javaflex falou, a documentação serve como referência para quem já sabe programar e está com dúvida na sintaxe, nos tipos de retorno ou no comportamento específico de um método ou classe. Resumindo, a sua crítica não faz sentido, por uma série de motivos:

1. É muito genérica e difusa. Assim não tem como fornecer um contra exemplo do que é uma boa documentação.
2. Você está simplesmente reclamando de algo que as documentações não prometem entregar
3. Sua proposta do que deveria ser feito no lugar também não é clara, ou seja, você critica mas não sugere nada como melhoria

Enfim, a impressão que eu tenho é que você quer programar orientado a copiar-e-colar pegando o que já tem pronto na Internet.

O ponto não é a documentção formal, de referência, e sim como usar os Componentes apresentados nela. Mesmo o Javadoc tem vários artigos linkados e exemplos.

Por exemplo, se eu posso instanciar uma Classe que extende JFrame direto no main e funciona, como é que eu iria saber que isso é uma má prática? Preciso de algo que explique que é, porque é, e como fazer o certo.

Esse tipo de coisa precisa ficar linckado na documentação, pra que quando você se deparar com uma classe, veja o link que te leva a um Artigo sobre como usar e como não usar.

Também citei o que deveria ser feito aqui:

Portanto, acredito que seria melhor se as Documentações tivessem várias Soluções prontas onde você pode pesquisar na Documentação a Solução que você precisa, e, ao encontrar você teria aquela “receita de bolo” mostrando quais Componentes usar e como Combiná-los; e os Componentes usados (as Classes, Interfaces, Métodos, etc.) teriam referência para as “receitas de bolo” nas quais eles são utilizados.

Ou seja, a Documentação deve serguir o estilo formal e padrão com as Classes, métodos, parâmetros, tipos de retorno etc., mas também “deve” possuir links para apresentar o que o programador precisa saber, para explicar como utilizar, como não utilizar, dar exemplos, etc.

E isso não é nada fora da realidade, o manual do php permite até mesmo que as pessoas postem notas/contribuições sobre cada tópico.

Nem sempre, se o código pudesse ser tão auto explicativo como gostaríamos que fosse nem precisaríamos documentar.

O problema real é que para cada solução de um sistema você deveria seguir um Padrão que seja o mais adequado para esta solução específica, e problemas específicos geralmente demandam Padrões específicos criados justamente para atendê-los da melhor forma possível. Veja por exemplo, como o StackOverFlow - afim de conseguir o máximo de performance - segue padrões que vão na contra mão do que se costuma apresentar por aí.

Mas se você cria Padrões, vai precisar usá-los com regularidade para não esquecer deles ou vai precisar armazenar explicações de como ele é e como utilizá-lo.

Então peço a sua experiência pessoal, você nunca fez um sistema/biblioteca e depois de um bom tempo sem mexer nele esqueceu várias coisas sobre ele, e, teve que gastar tempo estudando-o para relembrar?

Sim já aconteceu muitas vezes de esquecer algo e precisar relembrar, mas isso não impediu de conseguir dar manutenção quando o código estava auto explicativo, aos poucos relembrava olhando como já foi utilizado em outros lugares. Mesmo se tivesse uma documentação eu não iria conseguir assimilar aquilo imediatamente, o mais importante é saber usar no código, sendo mais fácil olhar como já foi usado.

Certo, então relembrar foi algo que lhe custou um certo tempo, a questão final é a seguinte:

if (tempoGastoParaRelembrarAnalisandoOCodigo > tempoGastoParaCriarUmaExplicacaoDidatica + tempoGastoParaEstudarAExplicacaoDidatica) {
    //Teria sido melhor ter criado e armazenado uma explicação, e estudá-la.
} else {
    //Foi melhor não ter criado a explicação, estudar o código é mais eficiente.
}

Onde:

• “tempoGastoParaCriarUmaExplicacaoDidatica” é o tempo que você gastaria para explicar o código, dar exemplos, dizer como usar e como não usar, etc, e arquivar essa explicação;
• “tempoGastoParaEstudarAExplicacaoDidatica” é o tempo que você gastaria estudando a explicação que você mesmo criou e armazenou, para poder relembrar de como seu código deve ser usado;
• “tempoGastoParaRelembrarAnalisandoOCodigo” é o tempo que você gastaria para relembrar como usar seu código e entendê-lo, sem utilizar uma explicação previamente criada para te ajudar com isso.

Mas a “explicação” da qual estou falando, na verdade, nem sempre precisa ser colocada em um Arquivo/Documento próprio, no Javadoc é muito comum termos exemplos e explicações de como usar a Classe logo no começo da página; mas é claro que criar isso terá um custo de qualquer forma (o “tempoGastoParaCriarUmaExplicacaoDidatica”).

Você concorda com minha linha de raciocínio?

Da mesma forma se fosse gastar tempo assimilando o que está escrito na documentação em relação ao que deve ser implementado de fato. Pelo menos eu acho mais fácil me basear em implementações já feitas que usem o componente que meu próprio time mantem. Já você prefere que esteja documentado algo que seu próprio time desenvolve. Então você sempre vai depender que tenha uma documentação mesmo para algo que é desenvolvido internamente.