¿Se considera una mala práctica incluir un número de error en el nombre de un método para una solución temporal?

Mi compañero de trabajo que es un hombre mayor me está bloqueando en una revisión de código porque quiere que nombre un método 'PerformSqlClient216147Workaround' porque es una solución para algún defecto ###. Ahora, mi propuesta de nombre de método es algo así como PerformRightExpressionCast que tiende a describir lo que realmente hace el método. Sus argumentos van en la línea de: "Bueno, este método se usa solo como una solución para este caso, y en ningún otro lugar".

¿Incluir el número de error dentro del nombre del método para una solución temporal se consideraría una mala práctica?

No mencionaría el método como sugirió su compañero de trabajo. El nombre del método debe indicar lo que hace el método. Un nombre como PerformSqlClient216147Workaroundno indica lo que hace. En todo caso, use comentarios que describan el método para mencionar que es una solución alternativa. Esto podría verse así:

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

Estoy de acuerdo con MainMa en que los números de error / defecto no deberían aparecer en el código fuente en sí, sino en los comentarios de control de fuente, ya que se trata de metadatos, pero no es terrible si aparecen en los comentarios del código fuente. Los números de error / defecto nunca deben usarse en los nombres de los métodos.

Nada es más permanente que una solución temporal que funcione.

¿Su sugerencia se ve bien dentro de 10 años? Solía ​​ser una práctica común comentar cada cambio con el defecto que solucionó. Más recientemente (como en las últimas 3 décadas), este estilo de comentario es ampliamente aceptado como una reducción de la capacidad de mantenimiento del código, y eso es con simples comentarios, no nombres de métodos.

Lo que propone es evidencia convincente de que sus sistemas de control de calidad y control de calidad son significativamente deficientes. El seguimiento de defectos y sus soluciones pertenecen al sistema de seguimiento de defectos, no al código fuente. El seguimiento de los cambios en el código fuente pertenece al sistema de control de fuente. La referencia cruzada entre estos sistemas permite el rastreo de defectos al código fuente .....

El código fuente está allí para hoy, no para ayer y no para mañana (como en, no escribes en la fuente qué planeas hacer el año que viene) ...

Entonces, ¿es una solución temporal? Luego use el nombre sugerido por el revisor, pero marque el método como obsoleto, de modo que usarlo generaría una advertencia cada vez que alguien está compilando el código.

Si no es así, siempre puede decir que 216147no tiene sentido en el código, ya que el código no está vinculado al sistema de seguimiento de errores (es más bien el sistema de seguimiento de errores que está vinculado al control de origen). El código fuente no es un buen lugar para referencias a tickets de errores y versiones, y si realmente necesita poner esas referencias allí, hágalo en los comentarios.

Tenga en cuenta que incluso en los comentarios, el número de error por sí solo no es muy valioso. Imagina el siguiente comentario:

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 el código fue escrito hace diez años, que se acaba de unir al proyecto, y que cuando preguntó dónde podría encontrar información sobre el error 8247, sus colegas dijeron que había una lista de errores en el sitio web del software de sistema de informes, pero el sitio web se rehizo hace cinco años y la nueva lista de errores tiene números diferentes.

Conclusión: no tienes idea de qué se trata este error.

El mismo código podría haberse escrito de una manera ligeramente 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.
}

Ahora tiene una visión clara del problema. Incluso si parece que el enlace de hipertexto al final del comentario está muerto hace cinco años, no importa, ya que aún puedes entender por qué FindReportsByDatefue reemplazado FindReportsByDateOnly.

Encuentro PerformSqlClient216147Workaroundmás informativo entonces PerformRightExpressionCast. No hay ninguna duda en el nombre de la función en cuanto a lo que hace, por qué lo hace o cómo obtener más información al respecto. Es una función explícita que será muy fácil de buscar en el código fuente.

Con un sistema de seguimiento de errores, ese número identifica de manera única el problema, y ​​cuando usted levanta ese error en el sistema, proporciona todos los detalles que necesita. Esto es algo muy inteligente que hacer en el código fuente, y ahorrará tiempo a los futuros desarrolladores al tratar de comprender por qué se realizó un cambio.

Si ve muchos de estos nombres de funciones si su código fuente, entonces el problema no es su convención de nomenclatura. El problema es que tienes un software con errores.

Hay valor en la sugerencia de su compañero de trabajo; proporciona trazabilidad al asociar los cambios en el código con el motivo, documentado en la base de datos de errores con ese número de ticket, por qué se realizó el cambio.

Sin embargo, también sugiere que la única razón por la que existe esa función es evitar el error. Eso, si el problema no fuera un problema, no querría que el software hiciera eso. Es de suponer que hace que el software para hacer su cosa, por lo que el nombre de la función debe explicar lo que hace y por qué el dominio del problema requiere que se haga; no por qué la base de datos de errores lo necesita. La solución debería verse como parte de la aplicación, no como una curita.

Creo que tanto tú como él han conseguido todo esto fuera de proporción.

Estoy de acuerdo con su argumento técnico, pero al final del día no hará mucha diferencia, especialmente si se trata de una solución temporal que se puede eliminar de la base de código en unos pocos días / semanas / meses.

Creo que deberías volver a poner tu ego en su caja y dejar que se salga con la suya. (Si él también estuviera escuchando, diría que ustedes deben comprometerse. Ambos egos vuelven a sus cajas).

De cualquier manera, usted y él tienen mejores cosas que hacer.

¿Incluir el número de error dentro del nombre del método para una solución temporal se consideraría una mala práctica?

Sí.

Idealmente, su clase debería mapear / implementar mejor un concepto en el flujo / estado de su aplicación. Los nombres de las API de esta clase deben reflejar lo que hacen al estado de la clase, para que el código del cliente pueda usar esa clase fácilmente (es decir, no especifique un nombre que literalmente no signifique nada a menos que lo lea específicamente).

Si parte de la API pública de esa clase básicamente dice "realizar la operación Y descrita en el documento / ubicación X", entonces la capacidad de otras personas para comprender la API dependerá de:

1. ellos saben qué buscar en la documentación externa

2. ellos sabiendo dónde buscar la documentación externa

3. ellos tomando el tiempo y el esfuerzo y realmente buscando.

Por otra parte, el nombre de su método ni siquiera menciona dónde está "ubicación X" para este defecto.

Simplemente supone (sin ninguna razón realista) que todos los que tienen acceso al código, también tienen acceso al sistema de seguimiento de defectos y que el sistema de seguimiento seguirá existiendo mientras exista el código estable.

Por lo menos, si sabe que el defecto siempre estará accesible en la misma ubicación y esto no cambiará (como un número de defecto de Microsoft que ha estado en la misma URL durante los últimos 15 años), debe proporcionar un enlace al problema en la documentación de la API.

Aun así, puede haber soluciones para otros defectos que afectan más que la API de una clase. ¿Qué harás entonces?

Tener API con el mismo número de defecto en varias clases ( data = controller.get227726FormattedData(); view.set227726FormattedData(data);realmente no te dice mucho y solo hace que el código sea más oscuro.

Puede decidir que todos los demás defectos se resuelven utilizando nombres descriptivos de la operación ( data = controller.getEscapedAndFormattedData(); view.setEscapedAndFormattedData(data);), excepto en el caso de su defecto 216147 (que rompe el principio de diseño de "menos sorpresa" - o si quiere decirlo así, aumenta la medida de "WTFs / LOC" de su código).

TL; DR: ¡ Mala práctica! ¡Ve a tu cuarto!

Los objetivos principales de un programador deben ser el código de trabajo y la claridad de expresión.

Nombrar un método de solución (... Solución). Parecería lograr este objetivo. Con suerte, en algún momento se solucionará el problema subyacente y se eliminará el método alternativo.

Para mí, nombrar un método después de un error sugiere que el error no se resuelve o que la causa raíz no se identifica. En otras palabras, sugiere que todavía hay una incógnita. Si está solucionando un error en un sistema de terceros, entonces su solución es una solución porque conoce la causa: simplemente no pueden o no lo solucionarán.

Si parte de la interacción con SqlClient requiere que realice una conversión de expresión correcta, entonces su código debería leer "performRightExpressionCast ()". Siempre puedes comentar el código para explicar por qué.

He pasado los últimos 4 años y medio manteniendo el software. Una de las cosas que hace que el código sea confuso de entender al saltar es el código escrito de la manera en que se debe solo al historial. En otras palabras, no funcionaría así si se escribiera hoy. No me refiero a la calidad, sino a un punto de vista.

Un compañero de trabajo mío dijo una vez: "Al solucionar un defecto, haga que el código sea como debería haber sido". La forma en que interpreto eso es "Cambia el código a cómo se vería si este error nunca existiera".

Consecuencias:

1. Por lo general, menos código como resultado.
2. Código sencillo
3. Menos referencias a errores en el código fuente
4. Menos riesgo de regresión futura (una vez que el cambio de código se verifica completamente)
5. Más fácil de analizar porque los desarrolladores no tienen que cargar con el historial de aprendizaje que ya no es relevante.

El código fuente no necesita decirme cómo llegó a su estado actual. El control de versiones me puede contar la historia. Necesito que el código fuente simplemente esté en el estado necesario para trabajar. Dicho esto, un comentario ocasional "// bug 12345" no es una mala idea, pero se abusa de él.

Entonces, cuando decida si desea nombrar o no su método 'PerformSqlClient216147Workaround', hágase estas preguntas:

1. Si hubiera sabido sobre el error 216147 antes de escribir el código, ¿cómo lo habría manejado?
2. ¿Cuál es la solución? Si alguien que nunca antes hubiera visto este código lo mirara, ¿podría seguirlo? ¿Es necesario verificar el sistema de seguimiento de errores para saber cómo funciona este código?
3. ¿Qué tan temporal es este código? En mi experiencia, las soluciones temporales generalmente se vuelven permanentes, como indica @mattnz.