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

40

É 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?

Geek
fonte
23
A pergunta que eu faria é "O que você pode fazer com os números de erros incorporados que ainda não pode fazer com seu banco de dados de erros?" Não consigo pensar em nenhum caso de uso real.
M. Dudley
6
@JensG É por isso que você colocá-lo na mensagem de confirmação e um logno arquivo lhe dará praticamente o exato mesma coisa, mas sem ocupar o arquivo ...
Izkata
11
@JensG E quando você corrigiu pontuações ou centenas de defeitos em um arquivo específico? A resposta óbvia é que você periodicamente limpar os IDs obsoletos, mas então você está de volta para grepping registo de VC ...
dmckee
3
Esta pergunta é o assunto do artigo da Ars Technica. Devemos listar erros no cabeçalho de um arquivo de origem? (publicado 15 dias após a publicação desta pergunta).
Peter Mortensen

Respostas:

107

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.

Thomas Owens
fonte
2
"e se você estiver usando um sistema moderno de controle de versão que suporte conjuntos de alterações, na verdade, estará perdendo informações sobre alterações". - você pode elaborar por favor?
7374 Geek
10
@ Geek, não sei o que explicar. Se você olhar para um arquivo que faz referência a um número de ID de bug, não verá outras alterações nos arquivos como resultado desse mesmo defeito, a menos que você pesquise os arquivos. Isso é o que é um conjunto de alterações - uma coleção de arquivos registrados juntos.
Thomas Owens
9
Eu também acrescentaria que, se você mudar para um novo sistema de rastreamento de bugs, todos esses números se tornarão instantaneamente inúteis. Eu encontrei isso no meu trabalho atual, onde alguns comentários têm números do software de rastreamento de bugs que não é usado há 10 anos.
17 de 26
2
Então, depois de mudar para o novo sistema de rastreamento de bugs, eles se tornam tão úteis como se nunca estivessem lá. Mas, assumindo que eles forneceram algum valor em algum momento e não fornecem valor negativo agora, por que não fazê-lo?
Cruncher
@ 17of26 - Eu imagino que você possa vincular bugs / problemas antigos a novos, se não houver outro mecanismo além de um comentário como "bug antigo do rastreador de problemas 1234".
Kenny Evitt
42

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.

rem
fonte
19
Talvez eu seja um pouco duro, mas se foo()não for chamado diretamente, o código deverá ser estruturado de tal maneira que não possa ser.
MetaFight 7/02
20
Ah, tentei escrever algo como exemplo, para tornar o texto mais concreto - não me leve muito a sério. Um caso melhor seria o caso em que você usasse uma biblioteca externa e a função que você usaria normalmente para uma finalidade específica apresentava um erro. Então, um comentário "Não ligue foo()aqui" seria razoável.
rem
16

É 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.

Kilian Foth
fonte
Quantos bugs exatamente você acha que são possíveis em um arquivo e se existem muitos provavelmente é hora de reescrever.
24414 Andy
11

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).

Neil Barnwell
fonte
2
que era um tipo de sistema de controle de versão (e que eu já vi usado operacionalmente em software houses há pouco tempo em 2006, e sem dúvida está em uso em algum lugar hoje).
Jwenting 07/02
11
@jwenting Eu vi perguntas sobre este mesmo site a partir de pessoas infelizes o suficiente para ser atualmente trabalhando em lojas onde que é prática corrente :-(
Carson63000
Usamos um ótimo sistema de controle de origem. Ninguém além de mim coloca comentários ao fazer o check-in do código. <shrug> Comento algumas coisas (como PLSQL, que nem sempre são rastreadas pelo SCM). Comento meu código para explicar, mas nunca o vinculo a erros específicos, mas sempre faço referência a erros no SCM para cometer comentários quando faço o check-in. Espero que, eventualmente, alguém aprecie isso.
Pedantic
11

É, 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).

Doc Brown
fonte
8

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á.

Parvez
fonte
3
Absolutamente. Às vezes, tenho a leve sensação de que os programadores ficam horrorizados com a redundância e evitam ter as mesmas informações acessíveis de maneiras diferentes. Isso é muito interessante, porque os programadores também ficam horrorizados com o desempenho ruim e, portanto, usam caches em seus programas. Mas armazenar em cache números de bug no código ao lado do local onde eles são mais úteis é considerado ruim? Mmmh.
JensG
Muitas vezes, há outra maneira de obter essas informações (no projeto em que estou trabalhando, seria right click > Team > Show Annotationsa culpa do arquivo atual), mas a diferença é que, com comentários, há descobertas - eles podem pular em você - e com anotações, você deve decidir conscientemente procurar por elas.
David Conrad
Pense, decida, clique, clique, clique, role. Por isso eu disse "cache no código". Se estiver lá, eu apenas vejo.
JensG
2
@JensG Ponto de vista interessante. Os caches podem melhorar o desempenho, mas também têm um custo de transporte. Se o cache tiver que ser preenchido, atualizado, invalidado, liberado e assim por diante por esforços humanos redundantes, questionaria a relação custo-benefício, especialmente considerando o quão terrível os humanos são em manter essas construções desnormalizadas em sincronia.
Jeffrey Hantin
7

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.

Pierre Arlaud
fonte
11
Veja o exemplo na questão - os comentários faria referência o banco de dados erro ...
Izkata
@ Izkata Mas esse é o ponto. O próprio banco de dados pode ter um campo "comentário" com o comentário. A questão não é ter um banco de dados de bugs ou não, mas se é bom mantê-lo no arquivo de origem. Eu acho que, mesmo que sejam comentários, eles devem ser mantidos no próprio banco de dados, porque é para isso que serve.
Pierre Arlaud
6

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.

JeffO
fonte
2

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 :)

jwenting
fonte
2

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.

ggb
fonte
2

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.

djechlin
fonte
2

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 .

Brian
fonte
Também existem avisos de direitos autorais para (ligeiramente redundantemente) informar os funcionários de que o arquivo pertence ao empregador. E talvez desencoraja compartilhamento ilegal (mesmo pelos funcionários), a julgar pela forma como muitas pessoas parecem pensar que os direitos autorais só se aplica se não é um aviso.
Bernd Jendrissek
1

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.

StingyJack
fonte
3
pergunta é sobre o comentário no início do arquivo de origem, logo após a mensagem de copyright - isso não tem nada a ver com comentários nos escopos mais estreitos
mosquito
Todas as respostas aqui estão falando exatamente sobre isso, no entanto. Se eu fizer alterações significativas em todo o arquivo de classe (reorganizar ou corrigir a formatação), não comentaria o arquivo de classe como o escopo?
StingyJack
0

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.

Fiammetta Castaldi
fonte
0

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.

hstoerr
fonte
isso parece não agregar valor substancial ao que já foi publicado em respostas anteriores #
306
0

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.

Fred Thomsen
fonte