Quanta documentação é suficiente?

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

Papadimoulis argumenta que você deveria

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

Essa é uma boa orientação ou há coisas específicas que devo criar?

Que tal alguns testes de usabilidade no 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 vontade avassaladora de explicar algo enquanto os observa rever o código, você tem o suficiente.

A perfeição está relacionada com não há mais um ano para aposentadoria, mais não há um ano mais para aposentador.
Antoine de Saint-Exupéry

Eu estive pensando sobre este tópico 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 que explicam onde os arquivos estão localizados (implementação versus intenção)

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

Acredito que o DDD tem voz na boa documentação - a classificação fornece contexto, o contexto cria limites e os limites levam a implementações intencionais (é aqui que ele pertence, e não precisa 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 o funcionamento dos códigos ser comentado ou não, mas a força motriz (lógica do domínio) não.

Às vezes esquecemos quem é o chefe - se o código mudar, a lógica ou o raciocínio do domínio não, 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" - é a linguagem que os desenvolvedores devem entender. Dizer a um desenvolvedor para adicionar um novo tipo a um Factory é melhor compreendido 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 .

Em uma nota lateral, as APIs que parecem favorecer muita documentação também são muito sensíveis ao domínio e ao contexto. Às vezes, duplicar a funcionalidade não é ruim (mesma coisa, contextos diferentes) e deve ser tratado como separado.

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

Por exemplo, você está trabalhando no setor médico. No 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?

Nesse caso, o paciente é um preso que foi transferido com segurança para um hospital externo. Sabendo disso, é mais fácil imaginar os eventos que levaram a esse ponto (e talvez o que ainda precisa acontecer).

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

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

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

Eu herdei centenas de linhas de código com muito pouca documentação. Tornou-se difícil para mim entender por que o código foi escrito. Depois que descobri por que o código foi escrito, tive que descobrir como usá-lo. Depois que descobri isso, tive que entender como deveria se comportar para poder oferecer suporte e manter o código.

Apenas por experiência, não faça comentários muito específicos ou você terá 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.

O suficiente para fazer você parar de se adivinhar.

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

Enxágüe e repita até que esse sentimento desapareça.

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

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

Para ajudar a calibrar as preocupações para que você possa priorizar os riscos, achei útil identificar algumas metas conhecidas como Limiar de Sucesso , que é o conjunto mínimo de metas que sua equipe acha que um projeto "bem-sucedido" deve alcançar. Do ponto de vista da documentação, um ToS de exemplo pode ser algo como "Um desenvolvedor deve ser capaz de criar um plug-in simples dentro de 4 horas após escolher 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-os 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 criar plug-ins com essas etapas ordenadas em mente.

Agora, como uma 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 falha do seu projeto (definido pelo Threshold of Success) esteja dentro de um limite tolerável. Geralmente, isso significa que você terá alguns riscos que a equipe concorda que não são muito preocupantes. Lembre-se de que você provavelmente não desejará 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.

O mínimo possível, mas o necessário

Não me lembro onde e quando ouvi isso pela primeira vez, mas é uma máxima com muitos aplicativos.

Quanto mais complexa a tecnologia ou o aplicativo, mais documentação seria necessária (obviamente), mas claramente você não quer perder tempo exagerando.

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

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

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

Portanto, a única maneira de saber se você já 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 com antecedência. Observe quanta explicação é necessária para fazer com que seus colegas entendam o 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 após algumas iterações, você terá uma idéia muito melhor de quanto é necessário.