Estudos sobre ganhos / perdas de produtividade da documentação do código

Após muita pesquisa, não consegui responder a uma pergunta básica referente a um suposto conhecido no mundo do desenvolvimento de software:

O QUE É CONHECIDO:

A imposição de uma política rigorosa na documentação adequada do código (sejam tags Doxygen, Javadoc ou simplesmente uma abundância de comentários) aumenta o tempo necessário para desenvolver o código.

MAS:

Ter documentação completa (ou até mesmo uma API) traz consigo ganhos de produtividade (supõe-se) em desenvolvedores novos e experientes quando estão adicionando recursos ou corrigindo erros no caminho.

A QUESTÃO:

O tempo adicional de desenvolvimento necessário para garantir essa documentação é compensado pelos ganhos de produtividade futuros (em sentido estritamente econômico)?

Estou procurando estudos de caso ou respostas que possam trazer evidências objetivas que apóiem ​​as conclusões que são tiradas.

Desde já, obrigado!

O artigo "O estilo tipográfico é mais do que cosmético" é bastante antigo, mas é muito interessante: http://portal.acm.org/citation.cfm?id=78611 .

Por ser antiga, ela não inclui todas as coisas sofisticadas que seriam possíveis atualmente, mas mostra claramente que a documentação do código é importante.

Para aqueles que, como eu, não têm acesso à biblioteca digital da ACM, criaram dois grupos de programadores e deram a eles o mesmo código para estudar. O grupo A recebeu apenas o código com os comentários usuais, o grupo B recebeu uma lista bastante impressa com índice, referência cruzada e todas as gentilezas possíveis em 1990.

Depois, eles pediram aos dois grupos para executar determinadas tarefas no código (por exemplo, estender uma função, encontrar um bug, ...) e os classificaram em termos de velocidade e qualidade das respostas.

Para equilibrar o grupo, eles tinham o mesmo número de programadores especialistas e juniores.

Bem, verificou-se que o grupo B (aquele com uma lista bem impressa) obteve uma pontuação melhor do que o grupo A em vários testes. E, em casos específicos, apenas os mais experientes do grupo A conseguiram superar o programador júnior do grupo B.

O artigo diz mais, mas é isso que consigo me lembrar da memória (eu ainda deveria ter o artigo impresso em algum lugar).

Para mim, pelo menos, parece óbvio que o código legível vale muito mais do que a documentação que serve apenas para compensar códigos mal escritos. Costumo considerar os comentários no código como um desafio para ver se consigo removê-lo reescrevendo o código e torná-lo mais auto-explicativo.

Não posso apoiar isso com nenhuma evidência concreta, exceto o bom senso.

Não tenho estudos para citar, mas tenho uma regra simples: se eu voltar ao meu código duas semanas depois e não conseguir descobrir imediatamente o que fiz, ele precisa de mais comentários ou precisa ser simplificado .

Certamente, como o seu código funciona deve ser documentado pelo próprio código. Mas o tempo gasto escrevendo comentários que explicam de maneira cuidadosa e sucinta o motivo pelo qual o código é escrito da maneira que quase certamente se paga a longo prazo, mesmo que você seja a única pessoa que mantém o código.

A vida útil de um software será gasta principalmente no estágio de manutenção; portanto, qualquer coisa que ajude o programador que vem depois de você a entender o que está acontecendo certamente fornecerá retornos financeiros, pois ajuda o desenvolvedor a acelerar mais rapidamente.

Em qualquer API pouco documentada, a API no código é praticamente inútil. Isso ocorre porque o poder da API vem da maneira como ela trabalha em conjunto como uma unidade inteira (não como métodos / objetos individuais funcionam).

Portanto, mais útil que a documentação verdadeira é um documento semelhante a um livro de receitas que explica os padrões de uso esperados da API e exemplos de como resolver algumas situações óbvias (que usam a maioria (não 100%) da API).

A decisão sobre se um determinado método é, sem ferramentas que provavelmente ainda não foram inventadas, é subjetiva demais para exigir que a documentação seja escrita.

Quaisquer práticas de melhor palpite, como "todos os métodos públicos" ou todas as classes em um determinado pacote etc., podem ajudar, mas são muito difíceis de recomendar além de casos de uso específicos.

Minha sugestão: ensine boas práticas aos desenvolvedores, como identificar métodos importantes para documentar (API formal ou informal, comumente usado, métodos de stub, complexo ou esotérico) e deixe que eles se governem.

(Intimamente relacionado: pode haver muita uniformidade nos padrões de codificação? )

^{Desculpas que não tenho estudos para citar, mas suspeito que este seja um problema em que qualquer tentativa de medi-lo afetaria muito o resultado para tirar conclusões gerais.}

Acho que precisamos separar o código "regular" das APIs públicas a esse respeito. Para código regular, cheguei a um acordo total com a maioria dos outros respondentes nesse código que deve ser auto-documentada e lida quase como uma prosa . Se meu código não é assim, geralmente é minha culpa; portanto, em vez de documentar, ele deve ser refatorado. Pequenos métodos que fazem apenas uma coisa de cada vez, trabalhando em um único nível de abstração, com um nome correto e descritivo , podem ser uma ótima maneira de conseguir isso.

O problema com os comentários é que eles apodrecem. Assim que você adiciona um comentário, ele começa a viver uma vida independente do código que acompanha. Qual é a chance de o próximo desenvolvedor que modificar o código também atualizará os comentários relacionados também? Na minha experiência, quase zero. O resultado final após algumas modificações é que o comentário confunde ou engana as pessoas em vez de ajudá-las.

As possíveis exceções são código com desempenho otimizado ou uso de um algoritmo específico . Nesse caso, é útil adicionar comentários para descrever por que o código se parece, uma referência ao algoritmo etc.

O trabalho seminal neste tópico é Código Limpo .

OTOH, uma API pública também deve estar bem documentada em Javadoc . Como pode ser usado por um número incontável de estranhos, com habilidades e suposições variadas, é preciso tomar precauções para torná-lo o mais simples e inequívoco possível. Isso ainda é em grande parte uma questão de design de API adequado, mas também há um papel importante na documentação.

O problema é se você economiza tempo documentando seu código versus todos os desenvolvedores subseqüentes que precisam tentar descobrir o que faz. Se seu código passar por uma revisão de código sem que ninguém faça perguntas sobre o que faz, provavelmente você está em boa forma. Não é muito difícil descrever as suposições que você faz sobre insumos. Digamos que seu método pegue um objeto inteiro e retorne um objeto string. O int pode ser nulo? Existe um valor mínimo / máximo (além de integer.MinValue / MaxValue)? Ele pode retornar uma string vazia ou nula? Isso gera alguma exceção? É claro que qualquer um pode encontrá-los por inspeção, mas se outros desenvolvedores usarem seu código em número suficiente, poupar a cada alguns minutos vale a pena. Além disso, fornece aos testadores uma ajuda para criar testes para confirmar seu código.

Este é certamente um tópico interessante, pois sempre houve discussões sobre se o desenvolvedor deveria gastar tempo criando ou mantendo documentos ou não, mas o fato é que o código deve ser bem escrito e muito bem comentado, desta maneira, quando o desenvolvedor visita novamente o código do que ele ou ela não precisa gastar tempo pensando em como o código foi escrito e o que deveria fazer em primeiro lugar, além disso, se um novo membro da equipe se juntar à equipe, ele também pode entender a funcionalidade e o funcionamento do código, como foi claramente documentado.

Portanto, o código deve ser muito bem comentado e deve ser um código auto-documentado que não exija nenhuma documentação externa.

Na minha carreira, vi códigos com níveis variados de documentação e qualidade (observe que documentação e qualidade são preocupações ortogonais). Eu preferiria que o tempo gasto na documentação fosse usado para melhorar a qualidade. Para o caso simples, existem ferramentas como o GhostDoc que podem analisar uma função e gerar comentários de documentos para você. Se o GhostDoc puder gerar um comentário significativo que diga o que sua função faz, então você obviamente alcançou o objetivo de ter funções bem nomeadas.

Em muitos casos, o GhostDoc nem pode começar a dizer o que uma função realmente faz. É melhor gastar seu tempo solucionando esse problema e (talvez) usando o ghostdoc para gerar automaticamente seu código.

Veja Código Limpo e PPP de Bob Martin para uma discussão mais profunda.