Os comentários do TODO fazem sentido? [fechadas]

Estou trabalhando em um projeto bastante grande e tive a tarefa de fazer algumas traduções para ele. Havia toneladas de etiquetas que não foram traduzidas e, enquanto eu vasculhava o código, encontrei esse pequeno pedaço de código

//TODO translations

Isso me fez pensar sobre o sentido desses comentários para si mesmo (e para os outros?), Porque tive a sensação de que a maioria dos desenvolvedores após a execução de um determinado pedaço de código e faz o que deveria fazer, nunca analisam isso até que tenham para mantê-lo ou adicionar novas funcionalidades. Para que isso TODOse perca por um longo tempo.

Faz sentido escrever esses comentários ou eles devem ser escritos em um quadro branco / papel / outra coisa em que permaneçam no foco dos desenvolvedores?

Costumo usar // todocomentários para coisas que precisam acontecer, mas não posso fazer imediatamente.

Também asseguro que os persigo - procuro por eles (o Visual Studio possui um bom recurso onde ele lista esses comentários para você) e asseguro que tudo seja feito.

Mas, como você diz, nem todos são diligentes com eles e, como muitos comentários, tendem a apodrecer com o tempo.

Eu diria que essa é mais uma preferência pessoal - desde que você documente o que precisa ser feito e o persiga, não importa se está dentro // todo, postit notes ou um quadro branco (onde eles também podem acabar não sendo sendo acionado).

Os IDEs modernos reconhecem os TODOcomentários e, como tais, são visíveis em seu próprio painel / janela / guia, portanto, teoricamente, não se perdem (estou pensando no Eclipse e no Visual Studio, ambos sei o suficiente para lembrar que eles o reconhecem).

Você pode até mesmo configurar comentário palavras adicionais, tais como FIXME, BEWAREou qualquer outra coisa que você deseja personalizar. No entanto, outros desenvolvedores do seu projeto precisarão personalizar o IDE da mesma maneira.

Agora, escrevi "teoricamente" porque, embora não se perca, o TODO se relaciona com mais frequência a algo que não é necessário para o aplicativo funcionar corretamente "no momento". E "no momento" pode se estender por 5 minutos a 5 anos, dependendo do tipo / tamanho do projeto :-)

Finalmente, na minha opinião, ainda faz mais sentido tê-los no código, no lugar certo, respondendo com precisão à pergunta "onde devo fazer a alteração" do que em algum outro lugar fora do código.

Edit: Como está escrito no artigo da Wikipedia sobre comentários , incluindo a data e o proprietário do TODO é considerada uma boa prática.

Pode fazer algum sentido, pelo menos eu as uso algumas vezes. O ponto principal é usar tags consistentes como TODOou FIXMEpara que elas possam ser facilmente encontradas com uma simples pesquisa de texto.

Por exemplo, as soluções "rápidas e sujas" são fáceis de rotular, algo como:

ConnManager.getConnection("mydatabase"); // FIXME: DB name should be configurable

Se o código faz o que deveria ser feito e ninguém reclama, o comentário não faz mal. Se houver tempo para embelezar o código, é fácil começar pesquisando FIXMErótulos.

No meu setor, os desenvolvedores são incentivados a fazer entradas do JIRA (ou etc) em vez de fazer comentários, porque nem todo mundo tem a chance de ver as // todoentradas. Mas, às vezes, em projetos grandes, um atributo personalizado é definido ao longo das linhas de:

[AttributeUsageAttribute(AttributeTargets.All, AllowMultiple = true)]
public class DeveloperNote : Attribute
{
    public DateTime EntryDate { get; set; }
    public string Description { get; set; }
    public DeveloperNote(int year, int month, int day, string desc)
    {
        EntryDate = new DateTime(year, month, day);
        Description = desc;
    }
}

E então um método pode ser decorado dessa maneira ...

[DeveloperNote(2011, 12, 13, "Make the db connection configurable")]

E os altos podem aparecer e colhê-los automaticamente. Pode ser um exagero para o simples // todolembrete, mas é eficaz. Também requer uma plataforma .NET.

TODO é apenas um subformulário de comentário. Os comentários são de grande utilidade se o escritor é habilidoso em saber o que transmitir e como transmiti-lo. Um senso de humor também pode ser aplicado aqui em pequenas doses para encantar os mantenedores anos depois.

Recebi uma ligação no ano passado que parte do meu código estava sendo aposentado. Fiquei bastante impressionado com o fato de ele estar em produção e sobreviver à manutenção por 16 anos. Esteja ciente de que seu código pode durar muito tempo. Comentários sobre intenção, necessidades futuras e assim por diante podem ajudar bastante alguém que daqui a alguns anos esteja olhando seu código pela primeira vez.

Na minha experiência, isso depende. O principal fator é se a equipe é ou não disciplinada o suficiente para acompanhar esses "pequenos" comentários. Se o fizerem, sim, fazem sentido. Caso contrário, esses comentários são apenas uma perda de tempo e você pode procurar outras opções, como, por exemplo, cartas de histórias.

Pessoalmente, uso os comentários do TODO ocasionalmente, mas eles geralmente têm vida curta e geralmente tenho apenas um número muito pequeno deles, como um, dois ou três. Eu os uso mais como um marcador na base de código do que qualquer outra coisa. Se eu esperar demais para cuidar deles, esqueço o que pensei que precisava "fazer".

Minha preferência seria sempre não usá-los e, em vez disso, usar cartões de histórias ou registros em atraso adequados ou similares. Use um mecanismo para uma tarefa.

Eu costumava escrevê-las no passado, mas descobri que você geralmente não as segue.

Portanto, agora eu os uso apenas para marcar coisas nas quais quero trabalhar logo após terminar o que estou ocupado. Por exemplo, eu implemento uma nova função e percebo que uma função que eu uso tem um pequeno bug; Eu faço um FIXME para corrigir isso para evitar atrapalhar minha tarefa atual.

Para me ajudar, nossas compilações de ICs estão configuradas para falhar se houver FIXMEs no código :-).

Se você perceber problemas em potencial que não podem ser resolvidos imediatamente, abra um ticket / bug / problema para eles. Dessa forma, eles podem ser priorizados como todos os bugs. Eu sinto que isso é muito melhor do que ter alguns problemas no banco de dados de erros e alguns no código como TODOs.

Opcionalmente, você pode colocar um TODO com o ID do bug :-).

Eu acho que os TODOcomentários, até certo ponto, fazem sentido. Especialmente se você está trabalhando de forma iterativa (como é comum em lojas ágeis e TDD), haverá coisas que você reconhece são vai ser necessário antes de tempo, mas que você não quer fazer o desvio para implementar a direita então e lá.

O que fica feio é quando esses comentários permanecem na base de código. Enquanto você estiver trabalhando ativamente em um recurso, não há problema em deixá-lo dentro, mas assim que se aproximar da conclusão do recurso, você deve se concentrar em se livrar dele. Se você não deseja realizar o trabalho de substituí-los por um código de trabalho adequado, considere pelo menos a funcionalidade relevante. Tomando emprestado o exemplo de @ JoonasPulakka, em que o código diz inicialmente

ConnManager.getConnection("mydatabase"); // FIXME: DB name should be configurable

você pode mudar isso para algo como

ConnManager.getConnection(GetDatabaseName());

por enquanto, GetDatabaseName () é um esboço que simplesmente retorna a mesma string com a qual você começou. Dessa forma, há um ponto claro de expansão futura e você sabe que quaisquer alterações feitas lá serão refletidas em qualquer lugar em que o nome do banco de dados seja necessário. Se o nome do banco de dados for moderadamente genérico, isso pode ser uma grande melhoria na capacidade de manutenção.

Pessoalmente, uso uma palavra-chave própria em vez de estritamente TODO, embora a intenção seja a mesma: marcar as coisas que sei que precisam ser revisadas. Além disso, antes de fazer check-in do meu código, faço uma pesquisa de código-fonte global para essa palavra-chave, escolhida de forma que normalmente ela não apareça em nenhum lugar do código. Se for encontrado, sei que esqueci algo e posso ir em frente e consertá-lo.

Quanto incluindo o programador nome / assinatura com o comentário, eu acho que é um exagero , se você tem um sistema de código-fonte controle de versão (você fazer , certo?). Nesse caso, seu recurso de culpa informará quem adicionou o comentário ou com mais precisão quem fez o check-in pela última vez em uma alteração que tocou no comentário. Por exemplo, no Visual Studio, isso é facilmente realizado usando o recurso "Anotar" encontrado entre os recursos de controle de origem.

Se você escrever um TODO ou FIXME com a idéia de que alguém irá corrigi-lo quando chegarem a esse código em um futuro indeterminado, eu diria que não se incomode. Eles organizarão o código e desorganizarão a parte dos relatórios do seu IDE que coleta essas informações.

Para serem úteis, eles devem fornecer um meio de marcar seu código como favorito no futuro (muito) próximo, para que você possa voltar ao estado mental mais rápido. Em outras palavras, você as coloca em seu código apenas para removê-las o mais rápido possível.

Qualquer coisa que tenha vida mais longa deve, de fato, ser colocada na sua base de bugs, onde ela pertence.

Há barulho suficiente em nossas vidas, não vamos criar uma nova fanfarra de coisas que gritam por atenção enquanto isso é necessário em outro lugar.

Meus 2 centavos

Normalmente, não faço comentários // TODO, mas mantenho todos eles em um arquivo separado. Ainda não consigo encontrar / escrever software on-line para gerenciá-los com facilidade, de modo que os arquivos TODO ainda estão sendo mais úteis para mim, porque quando abro o projeto depois de pouco tempo, esqueço o que fazer agora e depois olho para o arquivo TODO e faço o trabalho . Eu tenho "filename.cpp 354: recodifique este bla bla bla" e é muito mais útil do que pesquise // comentário TODO no arquivo. Eu fiz o // TODO earler quando estava com preguiça, mas apenas removi os // TODO-s antigos do arquivo de origem e não os corrigi quando o projeto funciona bem. Eu recomendo mover todos os // TODOs da fonte para um local separado e mantê-los juntos com outros todos, para que você possa priorizar as tarefas com facilidade. Prioridade é realmente uma coisa TODO difícil quando você obtém todos os seus TODOs em vários arquivos e projetos.

Eu acho ótimo, mas não sozinho. Por exemplo:

//TODO: ADD MY CLICK EVENT LOGIC
throw new Exception();
//Even a simple messageBox could suffice

Essa abordagem funciona muito bem com moderação. Embora eu deva dizer que criar o hábito de lançar exceções para lembrá-lo de concluir algum código não é realmente a abordagem mais profissional. Mas isso me salvou em alguns casos em que você acha que concluiu algo e até anotou que completou quando não o fez.

A enorme vantagem de fazer todos os comentários sobre qualquer um dos outros milhões de modos como se pode criar uma lista de tarefas é que todos os comentários viajam com o código para que não possam ser separados.

Provavelmente, o local mais apropriado para coisas como essa é o rastreador de problemas, e não o código.

Eu recomendo fortemente que todo TODO ou FIXME seja inserido em um log formal. Caso contrário, eles são facilmente pesquisáveis ​​e deve ser uma fase em cada iteração para verificar TODOs e FIXMEs pendentes. Eles podem ser catalogados e definidos para solução imediata, ou a equipe pode planejar corrigi-los no momento apropriado.

Finalmente, uma vez consertados, eles precisam ser removidos - se não forem eliminados de maneira sistemática após serem resolvidos, eles perderão sua eficácia.

Conclusão: eles são melhores do que não registrar problemas, mas você realmente precisa mantê-los.

O IntelliJ realmente alertará você se você tentar confirmar o código que possui novos TODOs. Portanto, você sempre pode interpretar um TODO como "isso realmente deve acontecer quando eu confirmar".

Quando você considera o "TODO" como um rótulo semântico para o seu comentário, acho que eles fazem sentido.

Nos padrões de codificação da minha empresa, especificamos que as iniciais do desenvolvedor responsável devem ser incluídas no TODO ( ou seja , digite "SAA TODO:"). Eu acho que isso é útil, pelo menos como uma convenção, porque, caso contrário, existe a tentação de deixar código abaixo do padrão com a nota TODO para algum desenvolvedor futuro lidar.

Felizmente, muitos IDEs podem ser configurados para adicionar esses comentários a uma lista de tarefas, permitindo que eles sejam tratados de maneira semelhante para criar gravações e não esquecidos indefinidamente.

Um método mais desagradável, porém eficaz, é provavelmente transformar seus comentários de tarefas em mensagens do compilador, assim como você e todo mundo vê quando o programa é compilado.

em Delphi:

{$message 'todo: free this thing when you know its not going to blow up'}

Na minha experiência, TODOdeve ser usado para indicar que um pedaço de código não é utilizável e informa ao leitor o que é necessário para torná-lo utilizável (localmente ou em outro lugar).

TODOas anotações não devem ser usadas para indicar que algum código seria melhor se modificado de alguma forma. Os exemplos incluem código sujo que seria mais sustentável se reescrito ou um recurso extra que ninguém precisa ainda. Essas anotações tendem a se acumular e grep TODOretornam resultados inúteis.