É geralmente útil incluir problemas do JIRA nos comentários do código?

8

De vez em quando, deixo comentários como

# We only need to use the following for V4 of the computation.
# See APIPROJ-14 for details.

ou

# We only need to use the following for V4 of the computation.
# See https://theboringcompany.atlassian.net/browse/DIGIT-827 for details.

Minha principal preocupação ao fazer isso é que isso aumenta nossa dependência do JIRA, de modo que esses comentários seriam totalmente discutíveis se migrássemos para outro sistema de gerenciamento de projetos. Embora eu não preveja que isso aconteça no futuro próximo, continuo cauteloso com o aumento do acoplamento dos componentes organizacionais (neste caso: código, repositórios de código e um sistema de gerenciamento de projetos).

No entanto , vejo o benefício de ter referências a decisões de design documentadas e inspiração de recursos em toda a base de código. Até onde eu sei, os benefícios são

um caminho claro para decisões de design, que ajuda na depuração e aprimoramento de segmentos específicos de código desconhecido,
menos comentários em várias linhas, o que torna o código mais limpo / menos intimidador para novos colaboradores,
um caminho claro para (potencialmente) as partes interessadas técnicas e não técnicas atuais, e
uma diminuição no número de perguntas "por que isso está aqui" por causa do mencionado?

— Mr_Spock
fonte

duplicata bastante flagrante de prática É bom comentar com o número da edição?

— Gnat

2

@gnat Não foi "flagrante", mas obrigado pela referência.

— Mr_Spock

1

Uma pequena vantagem é que ferramentas como IDEs podem facilmente criar hiperlinks para o ticket correspondente.

— axd

7

Eu tentaria evitar esses comentários. Embora eu ache que há um lugar para eles, onde você tem um requisito particularmente irritante. Sem isso, alguém pode querer refatorar o código. por exemplo.

//must log to the database instead of standard logging, 
//stupid requirement from those crazy DBAs!! see TKCT-1234

ou da mesma forma, você pode colocar um link

//work around stolen from this stackoverflow answer http://stackoverflow....

Mas não pelas razões pelas quais você declara aumentar o acoplamento. Na verdade, eu nomeio todos os meus ramos de recursos após o ticket para o qual eles são. Portanto, é possível rastrear todo o trabalho de volta para um ticket, se necessário, através do histórico de confirmação. (você também pode fazer coisas automáticas inteligentes se estiver se sentindo inteligente)

Não, não estou preocupado em mudar o sistema de bilhética. Mas o que percebi é que é super raro alguém olhar para os bilhetes assim que eles terminam.

Portanto, o comentário é útil porque indica sua futura substituição:

"Não, eu não cometi um erro, alguém me disse que tinha que ser assim. Olha! Aqui está o número do bilhete para provar isso!"

Mas eles não vão verificar o ingresso. A vida é muito curta.

Se você costuma colocar comentários de referência de ticket em todos os lugares, eles perdem o impacto. Em vez de ser uma bandeira "leia isso, é super importante!" eles apenas se tornam desorganizados.

Geralmente, os requisitos devem ser registrados por meio de testes. Se os testes forem aprovados, os requisitos devem ser atendidos, não precisamos nos preocupar com como eles foram originalmente declarados.

— Ewan
fonte

1

Concordo. Às vezes, procurei no banco de dados de rastreamento de trás para frente, mas não com frequência. Prefiro ter as informações relevantes nos comentários do código, para que estejam em um só lugar, por isso não sou a favor de colocar números de ticket para tickets trabalhados. Por outro lado, adquiri o hábito de deixar números de tíquetes futuros / futuros nos TODOs que eu poderia estar deixando no código atual, pois dá uma idéia de quando o TODO será resolvido e se alguém aparecer mais tarde e encontrar o TODO para um ticket que já está fechado, é uma bandeira que foi perdida quando o futuro ticket foi trabalhado.

— jia103

5

Para Comentários de Código, há muito pouca utilidade. Para comentários sobre controle de versão, eles são muito úteis pelos motivos descritos abaixo.

Os comentários do código realmente devem ser usados para ajudar a entender a intenção de coisas complicadas.

Tipos incorretos de comentários de código:

Updated EHS 10/24/2015 - se eu quisesse saber isso, usaria o controle de versão para descobrir quem escreveu quais linhas.
For spec 0.4 - isso pode fazer parte dos comentários de confirmação, mas não me ajuda a entender melhor o código
Outras variações do mesmo tipo de coisa.

Se existirem comentários de código, eles deverão ajudar a entender como o bloco de código está relacionado ao domínio comercial.

Se o JIRA e seu controle de versão estiverem vinculados, sim, eles farão sentido para confirmar as mensagens.

A referência ao ticket fornece rastreabilidade para as alterações necessárias no trabalho solicitado
O JIRA não é a única ferramenta de rastreamento de tickets capaz dessa sincronização.

Eu recomendo um formato de comentário parecido com o seguinte:

 DIGIT-827: We only need to use the following for V4 of the computation.

O JIRA e praticamente qualquer ferramenta com essa integração são inteligentes o suficiente para reconhecer o número do ticket e associá-lo ao ticket que está sendo resolvido. Isso significa que um URL completo não é necessário . Isso também significa que você pode obter os benefícios e fornecer comentários significativos para o commit específico, tudo em uma linha.

Ao visualizar o ticket no JIRA, você verá a lista de alterações com todos os comentários em contexto com a descrição, etc.

— Berin Loritsch
fonte

Com relação às iniciais / data / descrição da alteração, embora eu concorde que procurar no repositório é melhor, quero ressaltar que, no meu último projeto, eles concluíram que nossos cabeçalhos de arquivo padrão com o ano inicial dos direitos autorais combinados com um executar o histórico de software no cabeçalho do arquivo era evidência suficiente para manter os direitos autorais atualizados; portanto, se um arquivo de origem começou em 2013 e está sendo atualizado até hoje (2018), o hábito de atualizar o cabeçalho do arquivo permite que os direitos autorais continuem sem trabalho adicional , minimizando a chance de um lapso.

— jia103

@ jia103, Os cabeçalhos de direitos autorais são uma questão diferente de comentar que uma linha foi alterada nessa e nessa data usando as iniciais de alguém que pode ou não fazer parte da equipe no momento. Uma é uma coisa legal, a outra são informações redundantes simples que não fornecem contexto para a compreensão do código ao lado.

— Berin Loritsch

2

Sim, mas apenas em casos raros.

Geralmente, imagino que a maior parte do código seja escrita em conexão com um ticket do JIRA, por isso não comentaria rotineiramente com o ID do ticket - é para isso que serve a culpa do git. Mas, em alguns casos, o código pode ser contra-intuitivo - talvez a maneira mais óbvia de escrever o código não funcione e houve alguma discussão sobre o motivo de não estar no ticket. Nesse caso, eu consideraria adicionar um comentário com a referência do ticket.

Se uma parte do código precisar solucionar um bug conhecido em outra parte, eu também consideraria adicionar uma referência de ticket.

Não acho que isso o vincule muito ao JIRA, como se você deseja migrar do JIRA para um sistema alternativo, pode exportar seus problemas do JIRA como CSV e importá-los para outro sistema. O ID do problema pode mudar durante esse processo, mas você deve preservar o ID do ticket JIRA em algum lugar nos tickets importados.

— bdsl
fonte

1

Coloque os problemas de Jira nos comentários de confirmação e use um plug-in para vincular as confirmações ao Jira real.
Nossas mensagens de confirmação começam com:

JIRA: XBVS-1222 Fixes bugs...

Por exemplo, os ganchos entre bitbucket e jira vinculam as confirmações ao jira. Então é fácil ver a qual Jira ele se relaciona no eclipse, por exemplo, clicando com o botão direito do mouse no número da linha e selecionando "Mostrar histórico de revisões". Acho que é assim chamado. O número da sua edição e os comentários do Jira serão destacados na coluna número da linha, e passar o mouse com o mouse fornecerá os detalhes.

— bot_bot
fonte

1

O problema de Jira único é igual a ramificação única e cada confirmação é anotada com o identificador Jira para um problema específico, assim como você recomenda. Eu uso isso há muito tempo e, usando a culpa do git, é uma ótima maneira de rastrear alterações de código e suas razões sem poluir o código real com comentários inúteis.

— Andy

1

Certamente não é uma prática terrível incluir problemas do JIRA nos comentários do código, mas essa técnica combina manual / manual duas preocupações díspares (problemas e código) e pode exigir atualizações em vários sistemas / locais (JIRA, em qualquer lugar na origem em que o problema for mencionado, histórico de controle de versão).

Os comentários do código são problemáticos em geral porque geralmente não são atualizados.

Uma abordagem melhor seria encontrar uma maneira de integrar seu sistema de rastreamento de problemas ao seu sistema de controle de versão, para que as duas preocupações possam ser mantidas separadamente, de maneira automatizada.

— mcknz
fonte