Como lidar com um TODO em uma solicitação pull?

24

Quando analiso as alterações em uma solicitação pull, às vezes me deparei com um comentário com uma nota "TODO" que pode estar lá por diferentes razões, no nosso caso principalmente por causa de:

  • a solução usada para resolver um problema pode ser melhorada, mas exigiria um investimento de tempo significativamente maior. Um autor escolheu uma solução mais rápida, mas comentou que uma opção melhor está potencialmente disponível
  • existe um código temporário para solucionar um bug existente que deve ser corrigido em breve

Sabendo que eles TODOgeralmente permanecem na base de código durante a vida útil da base de código, como devo reagir a eles em uma solicitação pull? Como posso educadamente pedir para evitá-lo, ou se é realmente justificado, como posso garantir que o autor do PR o acompanhará posteriormente no futuro?

alecxe
fonte
Se os TODOs desfeitos estão se tornando um problema para sua equipe, você não pode designar alguém (ou, se você não tiver essa autoridade, pedir ao seu chefe que designe alguém) para passar algum tempo analisando todo o seu código e fazendo todos os TODOs?
nick012000
Um fator importante é se o TODO em questão é de natureza que pode ser resolvido por outros desenvolvedores que não o autor. Outro fator é avaliar pragmaticamente o risco ou a relevância desse TODO - é apenas lobo chorando?
amigos estão dizendo sobre rwong
Ter alguns TODOs em sua base de código não é problema.
Oliver Watkins

Respostas:

26

Quando você diz que "geralmente permanece na base de código durante toda a vida útil da base de código" em sua equipe / departamento / organização, considere o seguinte:

  • Escreva no seu DoD que TODO,FIXME ou marcas semelhantes devem ser evitadas.
  • Use uma ferramenta de análise de código estática, como o SonarQube para marcar automaticamente a compilação instável.
  • Permita-os temporariamente se, e somente se, houver um ticket correspondente no rastreador de problemas. Em seguida, o código pode parecerTODO [ID-123] Description ...

Como mencionado no meu comentário , a última afirmação provavelmente só faz sentido em um ambiente que não deixa os tickets apodrecerem (por exemplo, se você seguir uma política de erro zero ).

Pessoalmente, acho que às vezesTODO são razoáveis, mas não se deve usá-las excessivamente. Extraído de "Código Limpo: Um Manual de Artesanato em Software Ágil", de Robert C. Martin (p. 59):

TODOs são tarefas que o programador acha que devem ser feitas, mas por algum motivo não podem fazer no momento. Pode ser um lembrete para excluir um recurso obsoleto ou um apelo para que outra pessoa procure um problema. Pode ser uma solicitação para outra pessoa pensar em um nome melhor ou em um lembrete para fazer uma alteração que depende de um evento planejado. Qualquer outra coisa que uma TODOpode ser, é não uma desculpa para sair código ruim no sistema.

beatngu13
fonte
2
O ticket correspondente não permanecerá na lista de pendências para sempre? Vi TODOs e tickets permanecendo sem solução para sempre.
dzieciou
5
@dzieciou não necessariamente, mas, é claro, existe o risco de que ele permaneça lá para sempre também. No entanto, se você tiver um ticket, esse risco provavelmente será menor se comparado a apenas um comentário de código. Eu acho que depende da equipe / departamento / organização se isso faz sentido.
13
Se você tem uma política de não-tarefa, os desenvolvedores simplesmente deixam o comentário de tarefa fora do código e deixam o código rápido e sujo questionável. Má idéia.
RibaldEddie
8
Todos são uma forma de comunicação. Entre desenvolvedores. Às vezes, durante longos períodos de tempo. O uso da palavra TODO em um comentário de código não passa de açúcar sintático para uma preocupação específica.
RibaldEddie
2
Eu acho que a menção de adicioná-lo ao rastreador de problemas é fundamental aqui. Se você fizer isso, pode até acontecer que as pessoas comecem a corrigi-lo sem que você saiba. Eu já vi isso acontecer em uma organização; os problemas foram detectados apenas porque as pessoas gostavam de corrigir bugs, refatorar o código etc. Às vezes, pode ser bem legal.
Por Lundberg
5

TODO eles mesmos não são maus. Sou um grande fã de nunca ir além de uma camada e sempre corrigir um problema por ticket de rastreador.

Costumo usar o TODO ou o FIXME como uma maneira de lembrar que eu precisava ou queria voltar para corrigir um problema.

Por exemplo, posso chamar add (a, b) e adicionar um TODO para refatorar o método add. Não quero trabalhar no método add agora, mas quero voltar a ele.

Portanto, em uma solicitação pull, você verá TODO ou FIXME. Eu uso o FIXME, por exemplo, para alertar outros desenvolvedores de áreas de código sobre as quais eles têm responsabilidade, dos quais não devo mexer. Por exemplo, o FIXME add não pode aceitar números negativos.

Para contornar o problema de eles não serem vistos ou ignorados, eu uso um script que lista todas as linhas TODO FIXME e DEGUG. E isso é anexado à mensagem de confirmação.

É difícil ignorar uma mensagem de confirmação de 400 linhas que é todos os TODOs. Portanto, as pessoas as corrigem, já tocando no código em questão ou criando novos tickets e corrigindo o código do problema de forma independente.

Para ser justo, também asseguro que todos os projetos tenham tempo de limpeza de código. Sim, o be be pode estar pronto para ser lançado no dia 15, mas estava fazendo a limpeza do código do dia 15 para o dia 30. (pareça estranho, mas se você já gerenciou um produto, sabe que se tentar executar tarefas de baixa visibilidade antes do lançamento, nunca será permitido acessá-las. Outra coisa ganhará prioridade.)

coteyr
fonte
11
Concordo que TODOs não são maus por si só, mas usá-los com frequência é o que eu consideraria ruído. Também acho que uma mensagem de confirmação de 400 linhas é facilmente ignorada porque as pessoas tendem a pular esse texto. Além disso, muitas interfaces de Git / VCS (por exemplo, GitHub) truncam qualquer linha de assunto com mais de um determinado número de caracteres.
beatngu13
Sim, esse é o meu ponto, em torno de 4-5 linhas as pessoas tendem a querer limpá-lo. Então eles começam a fazer TODO. 400 linhas foi um exagero.
coteyr
Eu estaria interessado em saber como funciona o script para adicionar os TODOs à mensagem de confirmação.
21417 Simon
Existe um gancho "commit-msg" com o qual você pode se conectar.
coteyr
1

Acontecerá que há solicitações pull que não são perfeitas. No momento, estou fazendo um trabalho que pode ser feito "suficientemente bom" no tempo disponível, mas não perfeito. Então, enviei uma solicitação de recebimento, coloquei o TODO com comentários nos lugares certos do código e, ao mesmo tempo, adicionei outra solicitação de alteração para alterar as coisas de "bom o suficiente" para "perfeito".

Essa nova solicitação de alteração pode ser priorizada e será tratada quando for o item de maior prioridade. Se for decidido que precisa ser perfeito agora , será a próxima coisa a ser entregue.

Agora sua pergunta: "Como posso educadamente pedir para evitá-lo, ou se é realmente justificado, como posso garantir que o autor do PR o acompanhará posteriormente no futuro?" Com o que eu descrevo, isso parece um tanto estúpido. Se eu tiver a escolha entre enviar com atraso e enviar o que é bom o suficiente, não é sua decisão. Você pode perguntar ao seu gerente de produto, se quiser. E "garantir que o autor do PR o acompanhe"? Se você tem uma equipe, deve garantir que isso seja registrado em seus sistemas e, esperançosamente, sua equipe esteja suficientemente organizada para que as coisas registradas não se percam, e alguém a conserte eventualmente, quando não houver itens de maior prioridade. Lembre-se, é um esforço de equipe.

gnasher729
fonte
1

Se o seu projeto acompanhar itens pendentes no código-fonte com TODO comentários, você deverá permitir.

O fato de a presença de um TODOcomentário na solicitação pull estar incorreta, você deve informar que rastrear itens pendentes no código-fonte é uma má idéia. As coisas tendem a se perder ou ser ignoradas dessa maneira. Agora, se você está falando de uma solicitação pull para um "fork de trabalho", a situação é diferente. Um "garfo de trabalho" é exatamente isso - um trabalho em andamento. Mas um garfo como esse geralmente não requer uma solicitação de recebimento. As "Regras da Casa" sugeridas aqui são para solicitações pull do mestre ramificação .

Regra da Casa # 1 - Todas as confirmações para o mestre devem estar prontas para teste, pois o mestre é construído diariamente após qualquer check-in. Essas confirmações também devem incluir todos os testes adicionais necessários.

Se o TODO comentário estiver lá porque o código não terminou, ou os testes não terminaram ou o código não está pronto para o teste, esse código pertence a uma confirmação local, não a uma solicitação de recebimento. Ligue-me quando estiver pronto.

Regra da casa nº 2 - Todas as informações relacionadas a problemas abertos são armazenadas no rastreador de problemas. Tudo isso. Notas, rabiscos, palpites, o que for.

Se o TODOcomentário pertencer a um problema em aberto e não for uma correção real para esse problema, essas informações pertencerão ao rastreador de problemas. Dessa forma, antes que um problema seja fechado, todas as informações podem ser revisadas e verificadas, se necessário, para garantir que o problema seja realmente resolvido.

Regra 3 da casa - Todas as informações relacionadas às tarefas pendentes do projeto pertencem à fila de prioridade (ou seja qual for o nome do seu sistema).

Para esclarecimento, uma tarefa pendente do projeto é algo que precisa ser realizado no projeto com uma prioridade definida, seja um defeito que foi descoberto antes de gerar um ticket de problema ou a implementação de um requisito de design específico, ou um dos componentes necessários desse requisito.

Se o TODOcomentário estiver lá para dizer que o novo código impactará uma tarefa pendente ou para apontar outra coisa na base de código que precisa ser examinada que foi descoberta ao implementar o novo código, essas informações pertencem à fila de prioridade, ou a tarefa existente ou como uma nova.

Regra da casa # 4 - As sugestões pertencem à caixa de ideias (ou o que for).

Se o TODO comentário estiver sugerindo uma alteração no design ou na implementação do software, essas informações pertencerão à caixa de ideias do projeto, ou "vNext" ou "Design Notes", ou o que você tiver para esse tipo de coisa.

Regra da casa nº 5 - TODOcomentários não são permitidos no código fonte. PERÍODO.

Se você seguir essa regra, não precisará se preocupar com quem segue alguma coisa.

Mark Benningfield
fonte