Os comentários TODO fazem sentido? [fechadas]

81

Estou trabalhando em um projeto bastante grande e tenho a tarefa de fazer algumas traduções para ele. Havia toneladas de rótulos que não foram traduzidos e enquanto eu estava vasculhando o código eu encontrei este pequeno pedaço de código

//TODO translations

Isso me fez pensar sobre o sentido desses comentários para você mesmo (e para os outros?) porque tenho a impressão de que a maioria dos desenvolvedores depois de fazer um certo código e faz o que deveria fazer eles nunca olham para isso até que tenham que mantê-lo ou adicionar novas funcionalidades. Para que esse TODO seja perdido por um longo tempo.

Faz sentido escrever esses comentários ou eles devem ser escritos em uma lousa / papel / outra coisa onde permaneçam no foco dos desenvolvedores?

    
por Ivan Crojach Karačić 11.11.2013 / 10:46
fonte

17 respostas

103

Eu costumo usar // todo comentários para coisas que têm acontecer, mas não posso fazer imediatamente.

Eu também me certifico de que eu corri atrás deles - eu procuro por eles (o Visual Studio tem um ótimo recurso onde ele irá listar tais comentários para você) e garanto que as coisas são feitas.

Mas, como você diz, nem todo mundo é diligente com eles e, como muitos comentários, eles tendem a apodrecer com o tempo.

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

    
por 15.12.2011 / 10:52
fonte
56

IDEs modernos reconhecem os TODO comentários e eles são visíveis em seus próprios painéis / janelas / guias, então eles teoricamente não são perdidos (estou pensando no Eclipse e no Visual Studio, ambos sei o suficiente para lembrar que eles reconhecê-lo).

Você pode até configurar palavras de comentários adicionais, como FIXME , BEWARE ou qualquer outra coisa que você queira personalizar. No entanto, outros desenvolvedores em seu projeto terão que personalizar seu IDE da mesma maneira.

Agora, eu escrevi "teoricamente" porque, embora não seja perdido, o TODO mais frequentemente se refere a algo que não é necessário para que o aplicativo funcione 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, precisamente respondendo a pergunta "onde devo fazer a mudança" do que em outro lugar fora do código.

Editar: como está escrito no artigo sobre comentários da Wikipédia, incluindo a data e o proprietário do TODO é considerado uma boa prática.

    
por 15.12.2011 / 11:44
fonte
13

Pode fazer algum sentido, pelo menos eu os uso algumas vezes. O ponto principal é usar tags consistentes, como TODO ou FIXME , para que possam ser facilmente encontradas com a pesquisa de texto simples.

Por exemplo, soluções "rápidas e sujas" são convenientes para rotular, algo como:

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

Se o código faz o que é suposto fazer, e ninguém reclama, então o comentário não faz mal. Se houver tempo para embelezar o código, é fácil começar a pesquisar por FIXME labels.

    
por 15.12.2011 / 11:00
fonte
10

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

[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 superiores podem aparecer e coletá-los automaticamente. Pode ser um exagero para o lembrete simples de // todo , mas é eficaz. Também requer uma plataforma .NET.

    
por 12.04.2017 / 22:18
fonte
6

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

Pessoalmente, eu uso ocasionalmente comentários TODO, mas eles geralmente duram pouco e eu geralmente tenho apenas um pequeno número 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 muito tempo para cuidar deles, então esqueço o que achei que precisava "fazer".

A minha preferência seria sempre não usá-los e, em vez disso, usar cartões de histórias ou pendências apropriados ou semelhantes. Use um mecanismo para uma tarefa.

    
por 15.12.2011 / 10:54
fonte
6

TODO é apenas um subformulário de comentário. Os comentários têm grande utilidade se o escritor tiver habilidade suficiente para saber o que transmitir e como transmiti-lo. Um senso de humor também pode ser aplicado aqui em pequenas doses para deleitar os mantenedores anos mais tarde.

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

    
por 15.12.2011 / 14:36
fonte
5

Eu costumava escrevê-los no passado, mas descobri que você não costuma acompanhá-los.

Portanto, agora eu só os uso para marcar as coisas que quero trabalhar logo depois de 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 descarrilamento na minha tarefa atual.

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

Se você perceber possíveis problemas 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 do bug e alguns no código como TODOs.

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

    
por 15.12.2011 / 12:29
fonte
3

Acho que TODO comentários, até certo ponto, fazem sentido. Particularmente, se você estiver trabalhando iterativamente (como é comum em lojas ágeis e TDD), haverá coisas que você reconhece que são necessárias em pouco tempo, mas que você não quer fazer o desvio para implementar logo ali.

O que é feio é quando esses comentários permanecem na base de código. Enquanto você está trabalhando ativamente em um recurso, não há problema em deixá-los entrar, mas assim que você estiver mais perto de completar o recurso, você deve se concentrar em se livrar deles. Se você não quiser passar pelo trabalho de realmente substituí-los pelo código de trabalho adequado, considere pelo menos a funcionalidade relevante. Para emprestar o exemplo de @JoonasPulakka, onde o código inicialmente diz

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

você pode mudar isso para algo como

ConnManager.getConnection(GetDatabaseName());

com, por enquanto, GetDatabaseName () sendo um stub que simplesmente retorna a mesma string que você iniciou. 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 onde o nome do banco de dados é necessário. Se o nome do banco de dados for ainda moderadamente genérico, isso pode ser uma grande melhoria na capacidade de manutenção.

Pessoalmente, eu uso uma palavra-chave minha em vez de estritamente TODO , embora a intenção seja a mesma: marcar coisas que eu sei que precisarão revisitar. Além disso, antes de fazer o check-in do meu código, faço uma pesquisa global de código-fonte para essa palavra-chave, que é escolhida de modo que normalmente ela não apareça em nenhum lugar do código. Se for encontrado, sei que esqueci alguma coisa e posso ir em frente e corrigi-lo.

Quanto a incluir o nome / assinatura do programador com o comentário, acho que é um exagero se você tiver um sistema de controle de versão do código-fonte (você faz     

por 15.12.2011 / 14:28
fonte
2

Geralmente eu não faço // TODO comentários, mas mantenho todos eles em arquivo separado. Ainda não consigo encontrar / escrever software online para facilitar o gerenciamento deles, então os arquivos TODO ainda são mais úteis para mim, porque quando eu abro o projeto depois de pouco tempo eu esqueço o que fazer agora e então eu olho para o arquivo TODO e faço o trabalho . Eu tenho "filename.cpp 354: Recode este bla bla bla" e é muito mais útil, em seguida, pesquisar // TODO comentário no arquivo. Eu fiz // TODO earler quando eu estava com preguiça, mas eu apenas removi os antigos // TODO -s do arquivo de origem e não os corrijo quando o projeto funciona bem. Eu recomendo strongmente mover todos os // TODOs de souce para o lugar separado e mantê-los juntos com outros todos para que você possa priorizar as tarefas facilmente. A prioridade é realmente difícil TODO quando você tem todos os seus TODOs em vários arquivos e vários projetos.

    
por 15.12.2011 / 11:09
fonte
2

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 tenha que dizer que criar o hábito de lançar exceções para lembrá-lo de completar algum código, não é realmente a abordagem mais profissional. Mas isso me salvou em alguns casos em que você acha que completou algo e até mesmo escreveu que você completou quando você não o fez.

    
por 15.12.2011 / 16:53
fonte
2

Se você escrever um TODO ou FIXME com a idéia de que alguém irá consertá-lo quando eles vierem para esse código em algum futuro indeterminado, então eu diria que não se incomode. Eles vão sujar o código e confundir a parte de relatórios do seu IDE que coleta essas informações.

Para ser útil, eles devem fornecer um meio de marcar seu código para o (muito) futuro próximo, para que você possa voltar ao estado de espírito mais rapidamente. Em outras palavras, você os coloca em seu código apenas para removê-los o mais rápido possível.

Qualquer coisa mais longa deve ser colocada na sua base de bugs onde ela pertence.

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

Meus 2 centavos

    
por 15.12.2011 / 17:29
fonte
1

A grande vantagem dos comentários sobre qualquer um dos outros milhões de maneiras que se pode criar uma lista de tarefas é que os comentários enviam o código para que eles não se separem.

Provavelmente, o local mais apropriado para esse tipo de coisa é o rastreador de problemas, em vez do código.

    
por 15.12.2011 / 14:44
fonte
0

Eu recomendo strongmente que TODO TODO ou FIXME seja inserido em um log formal. Se não forem, 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 fixados, eles precisam ser removidos - se eles 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ê precisa mantê-los.

    
por 15.12.2011 / 14:36
fonte
-1

IntelliJ irá alertá-lo se você tentar cometer um código que tenha novos TODOs. Assim, você sempre pode interpretar um TODO como "isso realmente deve acontecer no momento em que eu me comprometo".

    
por 15.12.2011 / 15:41
fonte
-1

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 com o TODO ( isto é, , eu digitaria "SAA TODO:"). Eu acho que isso é útil, pelo menos como uma convenção, porque caso contrário, há a tentação de deixar código abaixo do padrão com a nota TODO para algum desenvolvedor futuro lidar.

Com ajuda, 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 registros e não serem esquecidos indefinidamente.

    
por 15.12.2011 / 16:35
fonte
-2

Um método mais detestável, mas eficaz, é provavelmente transformar seus comentários em mensagens do compilador, dessa forma você e todo mundo o vê quando o programa é compilado.

no Delphi:

{$message 'todo: free this thing when you know its not going to blow up'}
    
por 15.12.2011 / 15:19
fonte
-4

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

As anotações

TODO não devem ser usadas para indicar que alguma parte do código seria melhor se modificada de alguma forma. 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 fazem com que um grep TODO retorne resultados inúteis.

    
por 19.11.2015 / 23:08
fonte