Desabafo Documentação

Assuntos Gerais
#21

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.

#22

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?

#23

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.

#24

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?

#25

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.

1 curtida