Existem estudos empíricos sobre os efeitos de comentar o código fonte na qualidade, manutenção e produtividade do desenvolvedor? [fechadas]

11

Eu sou um defensor de comentar sobre o código fonte e documentar os produtos de software. É minha experiência pessoal e observação que trabalhar no código fonte que é rigorosamente comentado me ajudou de maneiras diferentes quando tive que cultivar software ou mantê-lo.

No entanto, há outro campo que diz que comentar não vale nada ou que seu valor é questionável. Inúmeros defensores da codificação sem comentar argumentam que:

  • Se um pedaço de código é bem escrito, é auto-explicativo e, portanto, não precisa ser comentado
  • Se um trecho de código não for auto-explicativo, refatore-o e faça-o auto-explicativo para que ele não precise de comentários
  • Sua suíte de testes é sua documentação ao vivo
  • Com o tempo, o código e os comentários ficam fora de sincronia e se tornam outra fonte de dores de cabeça
  • O Agile diz que o código de trabalho é mais importante do que pilhas de documentação, para que possamos ignorar com segurança os comentários escritos

Para mim, isso é apenas dogma. Mais uma vez, minha observação pessoal foi de que o software escrito por equipes de desenvolvedores inteligentes e experientes acaba tendo uma quantidade considerável de código que não é auto-explicativa.

Novamente, a API Java, API Cocoa, API Android, etc. mostram que se você deseja escrever e manter documentação de qualidade, é possível.

Dito tudo isso, conversas sobre prós e contras da documentação e comentários sobre o código fonte baseados em crenças pessoais geralmente não terminam bem e não levam a conclusões satisfatórias.

Como tal, estou procurando trabalhos acadêmicos e estudos empíricos sobre os efeitos da documentação de software, especialmente comentando o código-fonte, sobre sua qualidade e manutenção, bem como seus efeitos sobre a produtividade da equipe.

Você já se deparou com esses artigos e qual foi o resultado deles, se houver?

productivity documentation code-quality maintainability engineering Behrang Saeedzadeh
fonte
2
Eu acho que essa é uma pergunta interessante de qualquer maneira, mas não estou muito surpreso que ela possa ser encerrada aqui. É por isso que também postei isso no Quora.
Behrang Saeedzadeh
4
@gnat - Parece-me que "Que pesquisa foi feita nesse aspecto do campo do desenvolvimento de software?" é uma pergunta bastante diferente da solicitação "por favor, dê-me livros sobre um assunto" que não é bem-vinda.
21413 Josh Kelley
1
Apenas a partir da leitura do título: Não há estudos empíricos sobre os efeitos de qualquer coisa na qualidade. Se houvesse, este site não existiria.
eufórico
2
@Euphoric, suas duas afirmações se contradizem. Se ignorarmos o documento "louco" de 30 anos, não haverá conflito. De qualquer forma, não devemos ignorar as descobertas apenas porque são antigas, mas avaliar criticamente como elas se relacionam com o trabalho moderno (como deveríamos com novos resultados também).
3
@Euphoric Eu gostaria que você publicasse isso como resposta, para que eu pudesse minimizar sua total falta de pesquisa em sua afirmação geral. Existem toneladas de artigos e pesquisas, empíricas e outras, sobre os efeitos de diferentes técnicas na qualidade do software. Você estudou alguma coisa sobre engenharia de software?
Andres F.

Respostas:

9

Em "O efeito da modularização e comentários na compreensão do programa" (1981), Woodfield, Dunsmore e Shen descobriram que "os sujeitos cujos programas continham comentários eram capazes de responder a mais perguntas do que aqueles sem comentários".

No entanto, em "Aprendendo uma métrica para legibilidade de código" (2010), Raymond PL Buse e Westley Weimer descobriram que os comentários têm apenas um efeito limitado na legibilidade e na qualidade:

Do resumo:

Construímos uma medida de legibilidade automatizada e ... mostramos que essa métrica se correlaciona fortemente com três medidas de qualidade de software: alterações de código, relatórios de defeitos automatizados e mensagens de log de defeitos ... Nossos dados sugerem que os comentários por si só são menos importantes do que simples linhas em branco para julgamentos locais de legibilidade.

Na página 12:

Descobrimos que os comentários estão moderadamente bem correlacionados com a noção de legibilidade de nossos anotadores (poder relativo de 33%). Uma conclusão pode ser que, embora os comentários possam melhorar a legibilidade, eles geralmente são usados ​​em segmentos de código que começaram menos legíveis: o comentário e o código ilegível são efetivamente equilibrados. O efeito líquido parece ser que os comentários nem sempre são, por si só, indicativos de alta ou baixa legibilidade.

Lembre-se de que os proponentes "codificação sem comentar" não estão dizendo que o código sem comentários é melhor do que o código com comentários. Eles estão argumentando que um estilo particular de código sem comentários - um que extrai o código em métodos com nomes autoexplicativos, um que introduz variáveis ​​explicativas , um que possui um bom conjunto de testes - é melhor que o código que não faz essas coisas mas tem comentários. Isso pode complicar a aplicabilidade de qualquer estudo que tenha sido realizado.

Josh Kelley
fonte
1
O artigo de Woodfield et al é sobre uma variedade particular de comentários, aproximadamente equivalente ao que agora seria chamado Javadoc: "Especificamente, esta pesquisa tenta determinar se comentários curtos, inseridos imediatamente antes de um módulo lógico, podem ajudar na compreensão, descrevendo brevemente a função. do módulo lógico e ajudando a definir os limites do módulo lógico ".
Eu deveria ter acrescentado na época: isso não quer dizer que não tenha valor; na verdade, é um estudo interessante e bem construído. Eu apenas pensei que era necessário dizer que eles não estão aceitando todos os comentários.