Revisão de código por pares

Visão geral

Como os códigos de análises em ecologia, junto com os dados, se tornaram também um produto do projeto de pesquisa, boas práticas devem levar em conta a revisão não só da publicação científica, mas também do código de análises.

Nesta aula discutimos a revisão de código com um olhar sobre códigos de análises de dados, suas vantagens e também formas de incentivar e fomentar esta prática dentro dos grupos de pesquisa.

Geralmente, vamos revisar um repositório/código que está associado a uma publicação científica, ou que pelo menos, você conhece o projeto e tem mais informações sobre. Logo, esta ideia de revisão de repositório tem algumas diferenças dos padrões formais de revisão de código para desenvolvedores e outros profissionais da área de programação.

Por que fazer revisão de código?

• PROBLEMA:

  • Códigos e análises estão se tornando cada vez mais complicados e complexos na ciência, principalmente ecologia (Touchon & McCoy, 2016)
  • Revisão de código é praticamente inexistente na maioria dos trabalhos publicados em ecologia hoje em dia.

• CONSEQUÊNCIA:

  • Muitas retratações de artigos de alto impacto por erros em código que mudam resultados e conclusões

• SOLUÇÃO:

  • Mudanças culturais para trazer a revisão de código em todos os estágio da pesquisa.

• IMPEDIMENTO:

  • Poucos (ou nenhum) incentivos para a realização de revisão de códigos.

Vantagens da revisão do seu código de análise (Lee & Foster-Marks, 2024):

• Aumentar qualidade do código:

  • Clareza
  • Documentação
  • Detecção de erros

• Aumentar benefícios sociocognitivos da equipe/grupo/laboratório a longo prazo:

  • Transferência de conhecimentos e aprendizado
  • Soluções criativas e colaborativas de problemas
  • Confiança
  • Formação de comunidade
  • Aprendizado não só através de conteúdo, mas também com feedbacks construtivos

• Trazer mudança na cultura da pesquisa!

Culina et al. (2020) mostraram que 75% das revistas em Ecologia e Evolução contém políticas obrigatórias de compartilhamento de código e dados, apesar de que as políticas de compartilhamento de código não serem seguidas pela maioria dos autores (27% dos artigos).

Quando realizar a revisão do código/repositório de análise?

• Pré-publicação

  • Revisão feita por colegas, colaboradores, orientadores.

• Durante publicação / submissão

  • Revisão formal do código junto com o artigo submetido

• Pós-publicação

  • Revisar código em artigos já publicados. Esta revisão pode ser feita direto no GitHub via Issue ou Pull Request ou mesmo contactando inicialmente os autores (e talvez editores da revista onde o trabalho foi publicado)

Dicas para autores

Ajude o revisor a te ajudar!

Por que escrever um código bonito?

Mesmo que o código seja executado por máquina, ele também vai ser lido por humanos! Clareza, limpeza, estética consistente vão tornar a leitura mais fácil e também mais “barato” de se fazer ou propor modificações.

Eu acredito na criação do hábito de escrever desde o início códigos sempre pensnado que alguém (um estranho ou mesmo você no futuro) vai revisá-lo. Resista à tentação de achar que vai organizar o código depois que fizer todas as análises! Por isso a importância de se incorporar hábitos e dicas para escrita de código bonito, limpo e organizado.

Estilo de código é um conjunto de regras sobre sobre estética (alinhamento e espaçamento do código), nomenclatura (de variáveis, funções etc.), comentários, estruturação (por exemplo, evitar lógica complexa) etc. Essas regras ajudam a melhorar a clareza do código e a colaboração.

Ao longo da escrita do código, é saudável fazer uma pausa de vez em quando e revisar o estilo de escrita e o padrão de organização que você adotou no início e ver se você manteve ou não a consistência ao longo do tempo. É muito fácil começar adotanto uma padronização e terminar com outra diferente, principalmente se o código está sendo escrito ao longo de meses. Mas existem ferramentas para fazer isso de forma mais automatizada e rápida!

Existem vários estilos de escrita de código, e várias dicas por aí para seguir ou adaptar ao seu gosto. Alguns dos mais usados são o estilo de escrita do tidyverse, que tem o pacote R styler que pode ajustar seu código ao estilo usando um addin do Rstudio.

Outro pacote, além do styler que ajuda a padronizar um arquivo o pedaço de código a um estilo é o formatR.

O pacote lintr é muito útil para verificar o código quanto ao estilo, erros de sinstaxe e semântica, mas não vai modificar o arquivo por você. Ele faz um relatório de consistência do código

Veja algumas dicas beem gerais nesse e nesse roteiro para pensar e avaliar qual estilo de código você prefere seguir ou criar!

Comente/documente seus passos

Comentários ao longo dos scripts explicando porquê você está fazendo certas coisas ajuda muito a guiar o revisor/leitor ao longo do código. Escrever código em Rmarkdown e/ou Quarto resolve essa necessidade de explicar o passo a passo das análises, pois você pode separar a parte de explicação (texto) da parte de código Roteiro aqui.

Em arquivos .R você pode usar o bom e velho # para escrever comentários ao longo do código. Porém, a ideia aqui é diferente de um arquivo .Rmd ou .Qmd. Tenha cuidado com comentários demais que podem distrair o revisor/leitor ou poluir o código. Neste caso, os comentários no código devem ser pequenos alertas. Quanto mais comentários houver, mais provável será que o leitor os ignore.

Os comentários de código não devem ser um “band-aid” para nomes ruins ou código excessivamente complexo: em vez de adicionar um comentário, você pode renomear uma variável ou refatorar um trecho de código?

Assista essa brilhante palestra “Code smell and feels” da rainha, Jenny Bryan, sobre estilo de código!

Dicas para revisores

Lembre-se que há várias formas de se abordar um mesmo problema, o revisor não precisa impor sua forma. E cuidado para não impor estilo de escrita! Mas pode verificar inconsistências que venham a atrapalhar a leitura do código.

O que deve ser avaliado na revisão do código? Seguindo Ivimey-Cook et al. (2023), existem 3 tipos de erros em código:

• conceitual – implementando a função ou argumento errado

• programático – chamando o objeto ou coluna errada

• sintático – grafia incorreta de um estado ou função

E eles propõem uma forma organizada de revisar o código seguindo 4 Rs (em inglês):

• O código está como Reportado?

  • Verificação de consistência.
    
  • Métodos (no texto principal) e código devem coincidir.
  • Evita erros conceituais, como por exemplo, reportar que fez um modelo linear com distribuição de Possion, mas no código esquecer de especificar o argumento family=“Poisson” em um glm().

• O código Roda?

  • Erros programáticos e sintáticos podem fazer o código, ou partes dele, não rodar.
  • Pacotes não instalados (fora do ambiente) também ou versão diferente do revisor:
    • Pacotes que ajudam: renv, groundhog
  • Solução para outputs de análises que demoram muito: salvar arquivos intermediários para facilitar reprodutibilidade (e.g. extensão .rds)

• O código é Confiável (Reliable)?

  • Erros ainda podem se propagar mesmo que o código rode (produzir resultado incorreto mas reprodutível)
  • Confiança é examinar resultados intermediários do código para garantir que não há erros
  • Erros conceituais ou programáticos
    • ex: código seleciona/modifica a coluna errada
    • Esse tipo de erros (que rodam, mas estão conceitualmente errados ou indexados errado) escalonam com o número de linhas e complexidade do código

• Os resultados são Reprodutíveis?

  • Garantir que os resultados finais, quando o código é rodado novamente, correspondam àqueles reportados na análise e resultados do texto principal.
  • Tolerância com análises que lidam com estocasticidade: set.seed()
    • também levar em conta quantas casas decimas espera-se o mesmo resultado (precisão)

Baseado no checklist de revisão de código criado por Ivimey-Cook et al. (2023), nós elaboramos um arquivo de texto para guiar revisores de código:

Baixar checklist

Um exemplo de checklist para revisão de código (tirado de Ivimey-Cook et al. 2023)

Motivação final para revisão de código

• Ajuda a criar uma cultura de revisão de código entre colegas

  • Encoraja colaborações
  • Normaliza a existência de erros

• Incentivos para revisão:

  • co-autoria, agradecimentos, futuras colaborações…

• Crie um grupo de revisão de código!!

  • no lab
  • entre amigos/colegas

• Exemplo Peer Code Review group – SORTEE: https://github.com/SORTEE/peer-code-review/issues/8

Referências

Culina, A., Berg, I. van den, Evans, S. & Sánchez-Tójar, A. (2020). Low availability of code in ecology: A call for urgent action. PLOS Biology 18, e3000763.

Ivimey-Cook, E.R., Pick, J.L., Bairos-Novak, K.R., Culina, A., Gould, E., Grainger, M., Marshall, B.M., Moreau, D., Paquet, M., Royauté, R., Sánchez-Tójar, A., Silva, I. & Windecker, S.M. (2023). Implementing code review in the scientific workflow: Insights from ecology and evolutionary biology. Journal of Evolutionary Biology 36, 1347–1356.

Lee, C.S. & Foster-Marks, K. (2024). The Code Review Anxiety Workbook.

Touchon, J.C. & McCoy, M.W. (2016). The mismatch between current statistical practice and doctoral training in ecology. Ecosphere 7, e01394.