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

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

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

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.

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.

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.

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.

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.