É uma prática inadequada incluir um número de bug no nome de um método para uma solução temporária?

Meu colega de trabalho, que é um veterano, está me bloqueando em uma revisão de código porque ele quer que eu nomeie o método 'PerformSqlClient216147Workaround' porque é uma solução alternativa para algum defeito ###. Agora, minha proposta de nome de método é algo como PerformRightExpressionCast, que tende a descrever o que o método realmente faz. Seus argumentos seguem a linha de: "Bem, esse método é usado apenas como uma solução alternativa para este caso, e em nenhum outro lugar".

Incluir o número do bug dentro do nome do método para uma solução temporária seria considerado uma má prática?

Eu não nomearia o método como sugerido pelo seu colega de trabalho. O nome do método deve indicar o que o método faz. Um nome como PerformSqlClient216147Workaroundnão indica o que faz. Se houver algo, use comentários que descrevam o método para mencionar que é uma solução alternativa. Isso pode se parecer com o seguinte:

/**
 * Cast given right-hand SQL expression.
 *
 * Note: This is a workaround for an SQL client defect (#216147).
 */
public void CastRightExpression(SqlExpression rightExpression)
{
    ...
}

Concordo com a MainMa que os números de bug / defeito não devem aparecer no próprio código-fonte, mas nos comentários do controle de origem, pois são metadados, mas não é terrível se eles aparecerem nos comentários do código-fonte. Números de bug / defeito nunca devem ser usados ​​nos nomes dos métodos.

Nada é mais permanente do que uma correção temporária que funciona.

Sua sugestão parece boa daqui a 10 anos? Costumava ser uma prática comum comentar cada alteração com o defeito corrigido. Mais recentemente (como nas últimas três décadas), esse comentário de estilo é amplamente aceito como reduzindo a manutenção do código - e isso é com meros comentários, não nomes de métodos.

O que ele está propondo é uma evidência convincente de que seus sistemas de CQ e QA são significativamente deficientes. O rastreamento de defeitos e as correções de defeitos pertencem ao sistema de rastreamento de defeitos, não ao código-fonte. O rastreamento das alterações no código-fonte pertence ao sistema de controle de origem. A referência cruzada entre esses sistemas permite o rastreamento de defeitos no código fonte .....

O código fonte está lá para hoje, não ontem e amanhã (como em, você não digita na fonte o que planeja fazer no próximo ano) ...

Então é uma solução temporária? Em seguida, use o nome sugerido pelo revisor, mas marque o método como obsoleto, para que o uso gere um aviso sempre que alguém compilar o código.

Caso contrário, você sempre pode dizer que isso 216147não faz sentido no código, pois o código não está vinculado ao sistema de rastreamento de bugs (é o sistema de rastreamento de bugs que está vinculado ao controle de origem). O código-fonte não é um bom lugar para referências a tickets e versões de erros e, se você realmente precisar colocar essas referências, faça-o nos comentários.

Observe que, mesmo nos comentários, o número do bug por si só não é muito valioso. Imagine o seguinte comentário:

public IEnumerable<Report> FindReportsByDateOnly(DateTime date)
{
    // The following method replaces FindReportByDate, because of the bug 8247 in the
    // reporting system.
    var dateOnly = new DateTime(date.Year, date.Month, date.Day);
    return this.FindReportByDate(dateOnly);
}

private IEnumerable<Report> FindReportsByDate(DateTime date)
{
    Contract.Requires(date.Hour == 0);
    Contract.Requires(date.Minute == 0);
    Contract.Requires(date.Second == 0);

    // TODO: Do the actual work.
}

Imagine que o código foi escrito há dez anos, que você acabou de ingressar no projeto e que, quando perguntou onde poderia encontrar alguma informação sobre o bug 8247, seus colegas disseram que havia uma lista de bugs no site do software de sistema de relatórios, mas o site foi refeito há cinco anos e a nova lista de bugs tem números diferentes.

Conclusão: você não tem idéia do que é esse bug.

O mesmo código poderia ter sido escrito de uma maneira ligeiramente diferente:

public IEnumerable<Report> FindReportsByDateOnly(DateTime date)
{
    // The reporting system we actually use is buggy when it comes to searching for a report
    // when the DateTime contains not only a date, but also a time.
    // For example, if looking for reports from `new DateTime(2011, 6, 9)` (June 9th, 2011)
    // gives three reports, searching for reports from `new DateTime(2011, 6, 9, 8, 32, 0)`
    // (June 9th, 2011, 8:32 AM) would always return an empty set (instead of isolating the
    // date part, or at least be kind and throw an exception).
    // See also: http://example.com/support/reporting-software/bug/8247
    var dateOnly = new DateTime(date.Year, date.Month, date.Day);
    return this.FindReportsByDate(dateOnly);
}

private IEnumerable<Report> FindReportsByDate(DateTime date)
{
    Contract.Requires(date.Hour == 0);
    Contract.Requires(date.Minute == 0);
    Contract.Requires(date.Second == 0);

    // TODO: Do the actual work.
}

Agora você tem uma visão clara do problema. Mesmo que pareça que o link de hipertexto no final do comentário esteja morto há cinco anos, isso não importa, pois você ainda pode entender por que FindReportsByDatefoi substituído por FindReportsByDateOnly.

Acho PerformSqlClient216147Workaroundmais informativo então PerformRightExpressionCast. Não há nenhuma dúvida no nome da função sobre o que ela faz, por que ela faz ou como obter mais informações sobre ela. É uma função explícita que será super fácil de pesquisar no código fonte.

Com um sistema de rastreamento de bugs, esse número identifica exclusivamente o problema e, quando você apresenta esse bug no sistema, ele fornece todos os detalhes necessários. É uma coisa muito inteligente a ser feita no código-fonte e economizará tempo de futuros desenvolvedores ao tentar entender por que uma alteração foi feita.

Se você vir muitos desses nomes de função se o seu código-fonte, o problema não é sua convenção de nomenclatura. O problema é que você tem um software de buggy.

Há valor na sugestão do seu colega de trabalho; ele fornece rastreabilidade associando alterações ao código com o motivo, documentado no banco de dados de erros com o número do ticket, por que a alteração foi feita.

No entanto, também sugere que a única razão pela qual essa função existe é solucionar o bug. Se o problema não fosse um problema, você não gostaria que o software fizesse isso. Provavelmente, você fazer deseja que o software para fazer a sua coisa, então o nome da função deve explicar o que faz e por que o domínio do problema requer que ser feito; não é por que o banco de dados de bugs precisa dele. A solução deve parecer parte do aplicativo, não um curativo.

Eu acho que você e ele conseguiram tudo isso fora de proporção.

Concordo com seu argumento técnico, mas no final do dia não fará muita diferença, especialmente se for uma correção temporária que possa ser removida da base de código em alguns dias / semanas / meses.

Eu acho que você deveria colocar seu ego de volta na caixa, e apenas deixá-lo seguir seu próprio caminho. (Se ele estivesse ouvindo também, eu diria que vocês precisam se comprometer. Os dois egos voltam para suas caixas.)

De qualquer maneira, você e ele têm coisas melhores para fazer.

Incluir o número do bug dentro do nome do método para uma solução temporária seria considerado uma má prática?

Sim.

Idealmente, sua classe deve mapear melhor / implementar um conceito no fluxo / estado do aplicativo. Os nomes das APIs dessa classe devem refletir o que eles fazem com o estado da classe, para que o código do cliente possa usá-la facilmente (por exemplo, não especifique um nome que literalmente não signifique nada, a menos que você leia especificamente sobre ela).

Se parte da API pública dessa classe basicamente diz "executar a operação Y descrita no documento / local X", a capacidade de outras pessoas para entender a API dependerá de:

1. eles sabem o que procurar na documentação externa

2. eles sabendo onde procurar a documentação externa

3. eles gastando tempo e esforço e realmente olhando.

Por outro lado, o nome do seu método nem sequer menciona onde "local X" é para esse defeito.

Apenas assume (por nenhuma razão realista) que todo mundo que tem acesso ao código também tem acesso ao sistema de rastreamento de defeitos e que o sistema de rastreamento ainda estará disponível enquanto o código estável estiver disponível.

No mínimo, se você souber que o defeito estará sempre acessível no mesmo local e isso não será alterado (como um número de defeito da Microsoft que esteja no mesmo URL nos últimos 15 anos), você deverá fornecer um link para o problema na documentação da API.

Mesmo assim, pode haver soluções alternativas para outros defeitos, que afetam mais do que a API de uma classe. O que você vai fazer então?

Ter APIs com o mesmo número de defeitos em várias classes (na data = controller.get227726FormattedData(); view.set227726FormattedData(data);verdade não diz muito e apenas torna o código mais obscuro.

Você pode decidir que todos os outros defeitos serão resolvidos usando nomes descritivos da operação ( data = controller.getEscapedAndFormattedData(); view.setEscapedAndFormattedData(data);), exceto no caso do seu defeito 216147 (que quebra o princípio de design de "menos surpresas" - ou, se você quiser colocar dessa maneira, aumenta a medição de "WTFs / LOC" do seu código).

TL; DR: Má prática! Vá para o seu quarto!

Os principais objetivos de um programador devem ser o código de trabalho e a clareza de expressão.

Nomeando um método de solução alternativa (.... Solução alternativa). Parece conseguir esse objetivo. Esperamos que, em algum momento, o problema subjacente seja corrigido e o método de solução alternativa removido.

Para mim, nomear um método após um bug sugere que o bug não foi resolvido ou a causa raiz não foi identificada. Em outras palavras, sugere que ainda há um desconhecido. Se você estiver trabalhando com um bug em um sistema de terceiros, sua solução alternativa será uma solução porque você sabe a causa - eles simplesmente não podem ou não consertam.

Se parte da interação com o SqlClient exigir que você execute uma conversão de expressão correta, seu código deverá ler "performRightExpressionCast ()". Você sempre pode comentar o código para explicar o porquê.

Passei os últimos 4 anos e meio mantendo software. Uma das coisas que torna o código confuso de entender ao entrar é o código escrito da maneira que é apenas devido à história. Em outras palavras, não é assim que funcionaria se fosse escrito hoje. Não estou me referindo à qualidade, mas a um ponto de vista.

Um colega de trabalho disse uma vez "Ao corrigir um defeito, faça o código da maneira que deveria ter sido". A maneira como interpreto isso é "Altere o código para o que seria se esse bug nunca existisse".

Consequências:

1. Geralmente, menos código como resultado.
2. Código simples
3. Menos referências a erros no código fonte
4. Menos risco de regressão futura (depois que a alteração do código for totalmente verificada)
5. Mais fácil de analisar porque os desenvolvedores não precisam se sobrecarregar com o histórico de aprendizado que não é mais relevante.

O código fonte não precisa me dizer como chegou ao seu estado atual. O controle de versão pode me contar a história. Eu preciso que o código fonte esteja simplesmente no estado necessário para funcionar. Dito isto, um comentário ocasional do "// bug 12345" não é uma má idéia, mas é abusado.

Portanto, ao decidir se deve ou não nomear seu método 'PerformSqlClient216147Workaround', faça as seguintes perguntas:

1. Se eu soubesse sobre o bug 216147 antes de escrever o código, como eu o teria tratado?
2. Qual é a solução alternativa? Se alguém que nunca tinha visto esse código antes fosse vê-lo, seria capaz de segui-lo? É necessário verificar o sistema de rastreamento de bugs para saber como esse código funciona?
3. Quão temporário é esse código? Na minha experiência, soluções temporárias geralmente se tornam permanentes, como indica @mattnz.