Boa idéia de colocar números de bug em um comentário no início do arquivo de origem? [fechadas]

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

Acho que os dois métodos são terríveis por dois motivos principais. Primeiro, ele adiciona clutter e ruído ao arquivo, especialmente à medida que esses comentários envelhecem e se tornam irrelevantes para o estado atual do arquivo. Em segundo lugar, são informações duplicadas do que já é mantido no sistema de controle de versão e, se você estiver usando um sistema de controle de versão moderno que suporte conjuntos de mudanças, ele está realmente perdendo informações sobre alterações.

Se houver, considere a integração com seu sistema de rastreamento de defeitos. Algumas ferramentas permitem vincular um número de ID de defeito ou 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 vinculação dessa maneira. Claro, isso vem com a desvantagem de uma dependência dessas ferramentas para o projeto.

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

E se o código foi alterado de forma que não haja tentação de chamar foo() diretamente, remova esse comentário. Isso só iria irritar e explodir o código.

É uma prática totalmente horrível. Acrescenta esforço para obter um efeito que é pura duplicação; Em outras palavras, a única coisa que ele adiciona apenas usando 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 de origem sem acesso ao controle de versão, por exemplo, ao estudar uma impressão. Mas muito poucas pessoas são competentes o suficiente para seguir as complexidades do desenvolvimento de software, ao mesmo tempo que não conseguem entender o controle de versões.

Não.

Isso é o que as pessoas faziam antes de usar um sistema de controle de versão (ou seja, quando o código-fonte era apenas backup em zipfiles).

É, IMHO, uma ideia muito ruim. Após o número de revisão 100, você terá 90% de comentários e 10% de código. Eu não consideraria isso tão limpo e legível.

O único ponto nisso que vejo é quando você tem que trocar seu código entre os SCCs e, por qualquer razão, você não pode transferir o histórico entre os dois sistemas (mas mesmo quando você salva os comentários do histórico dessa maneira, você perderá o histórico de diferenças também, então salvar os comentários só ajudará um pouco).

Eu vejo que todos se opõem à ideia e deram uma razão histórica (era do controle pré-fonte) sobre o porquê das pessoas estarem fazendo isso.

No entanto, na minha empresa atual, os desenvolvedores de banco de dados estão seguindo essa prática e, além disso, identificam o número do bug em torno do trecho de 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, isso confunde o código, mas ajuda a descobrir o motivo pelo qual esse código está presente.

Um dos pontos do teste de Joel é

Do you have a bug database?

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

Eu acho que você tem dois problemas aqui. Primeiro, por que você deveria confiar puramente 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 porque a mudança foi feita e não apenas a mudança em si.

Segundo, se você tiver esse recurso, torne 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. Comentários dentro do código de trabalho estão lá para dizer por que ele está codificado dessa maneira.

Depois de colocar isso em prática, os hábitos formados facilitam o trabalho na base de código para todos.

O rastreamento associado de bugs e recursos, juntamente com o motivo pelo qual você está alterando esse arquivo, pode lhe dar uma ideia sobre o quanto você precisa pesquisar o histórico e possivelmente analisar os diffs. Eu tinha um pedido para "mudar de volta para a fórmula original". Eu sabia exatamente para onde ir no histórico de revisões e só revia um ou dois diffs.

Pessoalmente, o código remarcado 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 retirar linhas de código facilita a confusão.

Se você não tiver VCS com mensagens de confirmação e nenhum sistema de rastreamento de bugs com uma opção para deixar comentários, é uma opção, e não a ideal, para acompanhar as alterações. É melhor ter uma planilha com essa informação ou, se você estiver em um ambiente sem esses "luxos", um arquivo de texto em algum lugar perto de suas fontes.
Mas eu recomendo strongmente se você estiver em tal ambiente para começar a construir um caso para investir em um sistema de rastreamento de bug e VCS:)

Tenha isso em mente - o código geralmente é mais longo do que as ferramentas que o suportam. Dito de outra forma, 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 desordem de arquivos é irritante, abrir um arquivo e entender sua história 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 o log no código.

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

É um design menos modular em geral. Sob esta solução, agora os arquivos são uma mistura entre conteúdo e meta-dados. O Amazon S3 é outro exemplo de serviço para armazenar arquivos que não adicionam YAML da frente ou algo parecido para os 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, e. seu IDE favorito irá quebrar se ele não suportar seu VCS.

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

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

Se você estiver usando o software de rastreamento de versão ( Git , SVN , etc.), então você deve incluir essas notas em suas mensagens de commit. Ninguém quer vasculhar os cabeçalhos de todos os arquivos de código para gerar notas de versão ou ver uma visão geral de quais alterações foram feitas. Todos esses registros de alterações devem ser armazenados juntos, no histórico de acompanhamento da versão, no rastreador de defeitos ou em ambos.

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

Eu acho que existem outros elementos para essa discussão que são frequentemente esquecidos, mas são casos em que algum comentário de revisão é rápido 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 (método ou classe) indicando que uma alteração foi feita pode ser muito útil para resolver rapidamente conflitos de mesclagem ou check-in.

Da mesma forma, ao trabalhar em um ambiente no qual vários ramos (feature) estão envolvidos, fica mais fácil para uma terceira pessoa (build master) identificar o que fazer para resolver possíveis conflitos.

Sempre que você precisa se afastar da IDE e perguntar a alguém por que ela mudou alguma coisa, isso atrapalha a produtividade de ambos os membros da equipe. Uma nota 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, torna-se irrelevante quando a integridade de toda a alteração é modificada por uma correção sucessiva.

Costumava ser comum adicionar informações no resumo da função quando dependíamos de ferramentas externas (digamos, javadocs) para criar notas de lançamento a partir do código. É praticamente inútil ou redundante com ferramentas modernas de controle de versão.

Poderia fazer sentido apenas como um comentário em um código de código muito modular, se é preciso recorrer a alguma codificação obscura ou não estelar que os futuros desenvolvedores seriam tentados a mudar - sem saber o motivo por trás disso - como em um solução alternativa para um bug / falha de biblioteca.

Eu definitivamente não colocaria essas informações no início do arquivo - geralmente uma coisa dessas entra no sistema de tickets.

Existem, no entanto, alguns casos em que as referências ao sistema de tickets e / ou outra documentação fazem sentido. Por exemplo, se houver uma longa explicação do projeto 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 isso é curto, ele pertence ao próprio arquivo; se for longo e / ou for sobre uma imagem maior, você provavelmente vai querer colocá-lo em outro lugar e referenciá-lo.

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

Em certos arquivos críticos que passaram por muitas correções e aprimoramentos, essas listas se tornaram tão grandes que você precisa rolar por elas para chegar ao código. Quando greping essas listas podem resultar em vários falsos positivos, como um título de bug curto ou descrição curta é listada com cada um.

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