Boa ideia colocar um número de bug em um comentário no início do arquivo de origem? [fechadas]

É uma boa prática colocar números de bug no próprio arquivo dentro de um comentário de cabeçalho?

Os comentários ficariam assim:

 MODIFIED    (MM/DD/YY)
 abc 01/21/14 - Bug 17452317 - npe in drill across in dashboard edit mode

 cde 01/17/14 - Bug 2314558  - some other error description

Parece útil, mas é considerado uma má prática?

Eu já vi isso antes, tanto manualmente pelos autores quanto automaticamente por scripts e gatilhos integrados aos sistemas de controle de versão para adicionar informações de autor, comentário de check-in e data ao arquivo.

Eu acho que os dois métodos são terríveis por duas razões principais. Primeiro, ele adiciona confusão e ruído ao arquivo, especialmente à medida que esses comentários envelhecem e se tornam irrelevantes para o estado atual do arquivo. Segundo, são informações duplicadas do que já é mantido no sistema de controle de versão e, se você estiver usando um sistema moderno de controle de versão que suporte conjuntos de alterações, estará perdendo informações sobre as alterações.

Se alguma coisa, considere a integração com seu sistema de rastreamento de defeitos. Algumas ferramentas permitem vincular um defeito ou número de ID de tarefa em um comentário de check-in a um item na ferramenta de rastreamento. Se você tiver todos os seus defeitos, solicitações de aprimoramento e tarefas de trabalho na ferramenta, poderá fornecer o vínculo dessa maneira. Obviamente, isso vem com a desvantagem da dependência dessas ferramentas para o projeto.

Há exatamente um caso em que eu faria isso, a saber, como parte de um aviso para futuros programadores: "Não chame a função foo()aqui diretamente; isso causou o bug # 1234, ou seja, ..." e, em seguida, uma breve descrição do bug segue.

E se o código mudou de uma maneira que não há tentação de ligar foo()diretamente, remova esse comentário. Isso apenas irritaria e explodiria o código.

É uma prática completamente horrível. Acrescenta esforço para alcançar um efeito que é pura duplicação; em outras palavras, a única coisa que ele acrescenta ao usar apenas logs de confirmação é a possibilidade de criar inconsistência. Seus arquivos de origem ficam cheios de quantidades ilimitadas de coisas que você nunca vê.

A única vantagem que posso discernir é que você pode reconstruir o histórico da fonte sem acessar o controle de versão, por exemplo, ao estudar uma impressão. Porém, muito poucas pessoas são competentes o suficiente para acompanhar os meandros do desenvolvimento de software, ao mesmo tempo em que são incapazes de entender o controle de versão.

Não.

Foi o que as pessoas fizeram antes de usar um sistema de controle de versão (ou seja, quando o código-fonte era apenas backups em arquivos zip).

É, IMHO, uma péssima idéia. Após a revisão número 100, você terá 90% de comentários e 10% de código. Eu não consideraria isso limpo e legível.

O único ponto nisso que vejo é quando você precisa trocar seu código entre SCCs e, por qualquer motivo, não pode transferir o histórico entre os dois sistemas (mas mesmo ao salvar os comentários do histórico dessa maneira, você perderá o histórico do diff assim, salvar os comentários ajudará apenas um pouco).

Vejo que todos se opõem à idéia e deram uma razão histórica (era do controle pré-fonte) do porquê as pessoas estavam fazendo isso.

No entanto, na minha empresa atual, os desenvolvedores de bancos de dados estão seguindo essa prática e, além disso, marcam o número do bug em torno do código. Às vezes, acho isso útil quando você vê um bug no código e pode descobrir instantaneamente a correção de bug que introduziu esse problema. Se não tivermos essas informações no meu pacote de banco de dados, certamente não será fácil encontrar a causa raiz dessa implementação.

Sim, ele atrapalha o código, mas ajuda a encontrar o motivo pelo qual esse trecho de código está lá.

Um dos pontos no teste de Joel é

Você tem um banco de dados de bugs?

Essas informações podem ser mantidas em um banco de dados de bugs, se você achar que são importantes, mas apenas causariam ruído nos comentários.

Eu acho que você tem dois problemas aqui. Primeiro, por que você deveria confiar apenas no diff quando a maioria dos sistemas permite que você insira comentários de revisão? Como bons comentários de código, você descobre por que a alteração foi feita e não apenas a alteração em si.

Segundo, se você tiver esse recurso, faça uma boa prática colocar todos eles no mesmo lugar. Não há necessidade de procurar no arquivo linhas de código marcadas que não são mais necessárias. Os comentários dentro do código de trabalho existem para dizer por que é codificado dessa maneira.

Depois de colocar isso em prática, os hábitos formados tornam a base de código mais fácil de trabalhar para todos.

O bug associado e o rastreamento de recursos, juntamente com o motivo pelo qual você está alterando este arquivo, podem lhe dar uma idéia da profundidade que você precisa para aprofundar o histórico e possivelmente analisar as diferenças. Eu tive um pedido para "Voltar à fórmula original". Eu sabia exatamente para onde ir no histórico de revisões e revi apenas uma ou duas diferenças.

Pessoalmente, o código observado parece um trabalho em andamento para um problema que está sendo resolvido por tentativa e erro. Tire essa bagunça do código de produção. Ser capaz de inserir e remover linhas de código com facilidade apenas facilita a confusão.

Se você não possui VCS com mensagens de confirmação e nenhum sistema de rastreamento de bugs com uma opção para você deixar comentários, é uma opção, e não a ideal, para acompanhar as alterações.
É melhor ter uma planilha com essas informações ou, se você estiver em um ambiente sem esses "luxos", um arquivo de texto localizado em algum lugar próximo às suas fontes.
Mas eu recomendo fortemente que você esteja em um ambiente como esse para começar a criar um caso para investir em um sistema VCS e de rastreamento de bugs :)

Lembre-se disso: o código geralmente dura mais do que as ferramentas que o suportam. Dito de forma diferente, os rastreadores de problemas, o controle de versão e todos os outros scripts evoluirão ao longo do desenvolvimento. As informações são perdidas.

Embora eu concorde, a confusão de arquivos é irritante, abrir um arquivo e entender seu histórico sem recorrer ao uso das ferramentas sempre foi muito útil - especialmente se eu estou mantendo o código.

Pessoalmente, acho que há espaço para as ferramentas e para o log em código.

Eu sei que o Git não faz isso e a resposta simples é "por que diabos isso iria para lá?"

É um design menos modular em geral. Sob essa solução, agora os arquivos são uma mistura entre conteúdo e metadados. O Amazon S3 é outro exemplo de serviço para armazenamento de arquivos que não adiciona o front- end do YAML ou similar aos arquivos.

Qualquer consumidor de um arquivo é necessário para processá-lo através do sistema de controle de versão primeiro. Este é um acoplamento apertado, por exemplo, seu IDE favorito será interrompido se não suportar o seu VCS.

Não, não é uma boa prática rastrear suas correções de erros como comentários no código. Isso apenas gera confusão.

Também direi o mesmo para a mensagem de direitos autorais que você mencionou. Se ninguém fora da sua empresa verá esse código, não há motivo para incluir uma mensagem de direitos autorais.

Se você estiver usando o software de rastreamento de versão ( Git , SVN etc.), inclua essas notas nas mensagens de confirmação. Ninguém deseja pesquisar nos cabeçalhos de cada arquivo de código para gerar notas de versão ou ver uma visão geral de quais alterações foram feitas. Esses logs de alterações devem ser armazenados juntos, no histórico de rastreamento de versão, no rastreador de defeitos ou em ambos.

Se você estiver procurando uma boa leitura sobre esse assunto, recomendo o capítulo quatro do Código Limpo .

Eu acho que há outros elementos nessa discussão que são frequentemente esquecidos, mas existem casos em que alguns comentários de revisão são rápidos para uma equipe.

Ao trabalhar em um ambiente de equipe com uma base de código compartilhada e onde vários membros da equipe estão potencialmente trabalhando nas mesmas áreas de código, colocar um breve comentário de revisão no escopo correto (método ou classe) indicando que uma alteração foi feita pode ser muito útil para resolvendo rapidamente conflitos de mesclagem ou check-in.

Da mesma forma, ao trabalhar em um ambiente em que várias ramificações (de recursos) estão envolvidas, fica mais fácil para uma terceira pessoa (mestre de criação) identificar o que fazer para resolver possíveis conflitos.

Sempre que você precisa se afastar do IDE e perguntar a alguém por que eles mudaram alguma coisa, isso prejudica a produtividade de ambos os membros da equipe. Uma observação rápida no escopo correto pode ajudar a diminuir ou eliminar a maior parte dessa interrupção.

Qualquer informação de bug diretamente associada a um pedaço de código se torna irrelevante quando a integridade de toda a alteração é modificada por uma correção sucessiva.

Costumava-se adicionar informações no resumo da função quando tínhamos que confiar em ferramentas externas (por exemplo, javadocs) para criar notas de versão a partir do código. É principalmente inútil ou redundante com as modernas ferramentas de controle de versão.

Só poderia fazer sentido como um comentário em um pedaço de código muito modular, se alguém tivesse que recorrer a uma codificação obscura ou não estelar que os desenvolvedores futuros seriam tentados a mudar - sem saber o motivo - como em uma solução alternativa para um problema. erro / falha da biblioteca.

Definitivamente, eu não colocaria essas informações no início do arquivo - geralmente essas coisas pertencem a um sistema de tickets.

No entanto, existem alguns casos em que as referências ao sistema de tickets e / ou outra documentação fazem sentido. Por exemplo, se houver uma explicação longa do design ou descrição de alternativas. Ou informações sobre como testar as coisas ou explicações sobre por que isso foi feito exatamente dessa maneira. Se for curto, ele pertence ao próprio arquivo; se for longo e / ou for sobre uma imagem maior, você provavelmente desejará colocá-lo em outro lugar e referenciá-lo.

O projeto no qual estou designado no trabalho tinha esse tipo de lista de números de bugs no início de cada arquivo; no entanto, nenhum dos desenvolvedores ainda no projeto o anexa mais. A maioria deles pensa que é um desperdício inútil de espaço, pois é muito inferior ao rastreamento de erros cometidos em um arquivo usando nosso sistema de controle de versão.

Em certos arquivos críticos que sofreram muitas correções e aprimoramentos, essas listas se tornaram tão grandes que você precisa passar por elas para acessar o código. Quando greping, essas listas podem resultar em vários falsos positivos, pois um título curto de bug ou uma descrição curta são listados com cada um.

Em resumo, essas listas são, na melhor das hipóteses, inúteis e, na pior das hipóteses, um enorme e caótico desperdício de espaço que torna o código mais difícil de pesquisar e localizar.