ti-enxame.com

Quanta documentação é suficiente?

Quanta documentação técnica (para desenvolvedores futuros) é suficiente ? Existe uma proporção adequada entre as horas de codificação e as horas de documentação?

Papadimoulis argumenta que você deveria

produzir a menor quantidade de documentação necessária para facilitar o melhor entendimento,

Essa é uma boa diretriz ou há coisas específicas que eu deveria criar?

15
C. Ross

Que tal alguns testes de usabilidade do corredor? Mostre o código e a documentação para um desenvolvedor não familiarizado com o projeto. Quando você pode fazer isso sem uma necessidade irresistível de explicar algo enquanto os observa revisando o código, você já tem o suficiente.

25
JohnFx

A perfeição est atteinte non pas quand il n’y a plus rien à ajouter, mais quand il n’y a plus rien à retirer.
Antoine de Saint-Exupéry

12
Benoit

Eu estive pensando sobre este assunto por um tempo.

Minha conclusão é - não é uma questão de quantidade, mas de qualidade e contexto.

Por exemplo, uma estrutura de projeto adequada supera os comentários explicando onde os arquivos estão localizados (implementação vs. intenção)

Da mesma forma, a classificação para esclarecer o contexto supera a nomenclatura (Id em um paciente -> Patient.Id).

Acredito que o DDD tem uma palavra a dizer na boa documentação - a classificação fornece contexto, o contexto cria limites e os limites levam a implementações intencionais (é aqui que isso pertence, em vez de precisar existir).

O código em si não é bom o suficiente para ser considerado documentação. O problema na maioria dos casos não reside no fato de que o funcionamento dos códigos é comentado ou não, mas sim a força motriz (lógica do domínio).

Às vezes esquecemos quem é o chefe - se o código muda, a lógica ou o raciocínio do domínio não deveriam, mas se a lógica ou o raciocínio do domínio mudar, o código definitivamente mudará.

A consistência também é muito importante - a convenção por si só é inútil se não for consistente.

Os padrões de design não são apenas 'boas práticas' - é uma linguagem que nós, desenvolvedores, devemos entender. Dizer a um desenvolvedor para adicionar um novo tipo a um Factory é melhor entendido do que adicionar um novo tipo a um método (onde o contexto e a consistência são fracos ou ausentes).

Metade da luta é familiaridade.

Por outro lado, as APIs que parecem favorecer uma grande quantidade de documentação também são muito sensíveis ao domínio e ao contexto. Às vezes, duplicar funcionalidade não é ruim (mesma coisa, contextos diferentes) e deve ser tratado separadamente.

Em termos de comentários, é sempre bom apontar a lógica de domínio por trás do raciocínio.

Por exemplo, você está trabalhando na indústria médica. Em seu método, você escreve "IsPatientSecure = true;"

Agora, qualquer programador decente pode descobrir que o paciente está sendo marcado como seguro. Mas por que? Quais são as implicações?

Neste caso, o paciente é um recluso que foi transferido em segurança para um hospital fora das instalações. Sabendo disso, é mais fácil imaginar os eventos que levaram até esse ponto (e talvez o que ainda precisa acontecer).

Talvez esta postagem pareça filosófica na melhor das hipóteses - mas lembre-se de que é sobre 'raciocínio' ou 'lógica' que você está escrevendo - não sobre código.

3
Shelakel

O suficiente para fazer você parar de tentar adivinhar.

Se a qualquer momento durante o seu trabalho você disser "hmm, talvez eu deva documentar isso", vá em frente e faça. Então, se você escreveu alguma documentação e pensa "talvez eu deva explicar isso mais", vá em frente e faça isso.

Enxaguar e repetir até que a sensação vá embora.

1
Mark Canlas

Descobri que uma abordagem orientada a riscos como a apresentada no livro de George Fairbanks Just Enough Software Architecture funciona extremamente bem para entender quanta documentação é suficiente. Você pode ler a seção que apresenta este conceito (capítulo 3) em seu site, mas a ideia principal é:

  • Expresse as coisas que o preocupam sobre a "compreensão do sistema" como riscos
  • Priorize os riscos
  • Mitigue os riscos até que sua equipe sinta que o risco do projeto foi suficientemente reduzido. Neste caso, você provavelmente estará criando algum tipo de documentação.

Para ajudar a calibrar as preocupações para que você possa priorizar os riscos, descobri que é útil identificar algumas metas conhecidas como Limiar de sucesso , que é o conjunto mínimo de metas que sua equipe considera um projeto "bem-sucedido" deve alcançar. De uma perspectiva de documentação, um exemplo de ToS pode ser algo como "Um desenvolvedor deve ser capaz de construir um plug-in simples em 4 horas após pegar a estrutura pela primeira vez."

Agora identifique alguns riscos. Com o sistema que você construiu (ou está construindo), quais são as coisas que mais preocupam sua equipe? Expresse-as como declarações de risco. Eu gosto do estilo de consequência de condição do SEI, mas existem outros. Exemplos:

  • O modelo de dados é grande e complexo; os desenvolvedores podem não saber quais elementos de dados usar em uma determinada situação.
  • O sistema possui limites de conexão API para aumentar a confiabilidade; os desenvolvedores podem ultrapassar acidentalmente o limite de conexão.
  • Os plug-ins são consumidos em várias etapas sequenciais; os desenvolvedores podem não construir plug-ins com essas etapas ordenadas em mente.

Agora, como equipe, priorize os riscos. A votação múltipla funciona extremamente bem.

Reduza os riscos de prioridade máxima e repita começando com a identificação até que o risco de seu projeto falhar (definido pelo Limite de sucesso) esteja dentro de um limite tolerável. Geralmente, isso significa que você terá alguns riscos que a equipe concorda que não são uma grande preocupação. Lembre-se de que você provavelmente não deseja mitigar todos os riscos. Um exemplo de estratégia de mitigação para o último risco acima pode ser a criação de um tutorial.

1
Michael

Eu concordo com a citação de Papadimouslis. O código-fonte pode falar por si mesmo, mas não pode dizer por que ele existe, como deve ser usado e como o código deve se comportar.

Não conheço uma boa proporção.

Herdei centenas de linhas de código com muito pouca documentação. Ficou difícil para mim entender por que o código foi escrito. Depois de descobrir por que o código foi escrito, tive que descobrir como usar o código. Depois que descobri isso, tive que entender como ele deveria se comportar para poder dar suporte e manter o código.

Apenas por experiência própria, não faça comentários muito específicos ou você acabará tendo que manter o código real E a documentação. É um pesadelo quando a documentação e o código estão fora de sincronia.

1
Kin

O mínimo possível, mas tanto quanto for necessário

Não me lembro onde e quando ouvi isso pela primeira vez, mas é uma máxima com muitas aplicações.

Quanto mais complexa for a tecnologia ou o aplicativo, mais documentação será necessária (obviamente), mas é claro que você não quer perder tempo exagerando.

O 'teste de corredor' da JohnFx é válido. Mas confie em si mesmo; você desenvolveu o código e, portanto, você, entre todas as pessoas, deve ter uma noção dos elementos que precisam de atenção extra e dos elementos que serão óbvios para todos. Pense nas dificuldades que você teve para desenvolver o código e provavelmente terá uma ideia do que outro desenvolvedor verá ao examinar o seu código.

Esqueça qualquer relação entre o esforço gasto na codificação e o esforço gasto na documentação.

1
cjmUK

Eu acredito que você não pode colocar isso em regras exatas. O motivo da documentação é fornecer o conhecimento que não é facilmente obtido do código bruto de uma forma que outros possam entender e talvez até mesmo manter o referido código bruto.

Portanto, a única maneira de saber se documentou o suficiente é perguntar ao público-alvo se é bom o suficiente. Eu acredito que o processo de "revisão por pares" é muito bom em fazer isso no início. Observe quantas explicações são necessárias para que seus colegas entendam do que você está falando e trabalhe para minimizar isso.

Se você nunca fez isso antes, não pode estimar quanto trabalho será necessário, mas depois de algumas iterações terá uma ideia muito melhor de quanto é necessário.

0
user1249