Vi muchos números de problemas de los comentarios del código jQuery . (En realidad, había 69 números de problema en el código jQuery). Creo que sería una buena práctica, pero nunca he visto ninguna guía.
Si es una buena práctica, ¿cuáles son las pautas para esta práctica?
Respuestas:
En general, no lo consideraría una buena práctica. Pero en casos excepcionales, puede ser muy útil, es decir, cuando el código tiene que hacer algo poco intuitivo para solucionar un problema complejo y, sin ninguna explicación, existe el riesgo de que alguien quiera "arreglar" este extraño código y así romperlo. , al explicar el razonamiento se traduciría en un gran comentario que duplica la información del problema.
Creo que es suficiente agregar el número de problema al mensaje de confirmación cuando confirma la solución relacionada a su sistema de control de código fuente.
Por ejemplo:
Error # 203: Las conexiones de la base de datos ya no se agota después de 30 segundos.
Encuentro que agregar números de problemas, nombres de desarrolladores o fechas en que se han realizado cambios en el código solo contamina la base de código y realmente debe ser administrado externamente por su sistema de control de fuente.
Estoy completamente en desacuerdo con los otros carteles aquí!
Los comentarios de código con referencias de seguimiento pueden ser de gran ayuda para la programación de mantenimiento.
Si estoy rastreando un error y me estoy acercando al área del código, ver que se ha cambiado recientemente y que tengo un enlace al contexto del cambio es un envío de Dios.
Sí, tenemos control de código fuente, pero puede ser bastante lento verificar archivos y módulos individualmente. Usted quiere estas cosas que saltan a la vista de los cambios recientes.
Probablemente los desaprobaría, ya que veo los realmente antiguos en la base del código, pero hay muy pocos inconvenientes para mantener los más recientes y mucho tiempo de desarrollador potencialmente ahorrado si los usa de manera inteligente.
De hecho, creo que estas pequeñas referencias a su sistema de seguimiento de errores son preferibles a los comentarios detallados en el código.
git gui blame <filename>proporciona una GUI muy rápida para explorar el historial de código si usa git. El uso de una herramienta para combinar comentarios de código con historial permite una documentación mucho mejor para el código que cualquier comentario en línea. Es decir, si te molestas en ir a escribir buenos mensajes de confirmación (un buen mensaje de confirmación debe ser aproximadamente igual a un mensaje de correo electrónico que explique por qué se debe aplicar ese parche).
Si se suscribe a una política de "Código limpio", probablemente deba preguntarse si es una buena práctica agregar comentarios. Si el código solo se puede aclarar con un comentario, entonces, seguro, agregue uno, de lo contrario, debería poder comprender fácilmente lo que hace su código simplemente al leerlo (siempre que esté usando nombres razonables para sus variables, métodos, etc.).
Independientemente de su opinión personal sobre si comentar es una buena práctica o no, un comentario debe contener información que sea de valor directo para el código al que se refiere el comentario. En este caso, la pregunta es si agregar un número de problema agrega valor al código. El problema que veo al agregar el número de problema es que puede tener una sección de código que podría modificarse en gran medida para satisfacer varios problemas, y después de un tiempo, podría ser imposible identificar correctamente los cambios relacionados con un problema específico. Los problemas posteriores, por ejemplo, pueden requerir que el código relacionado con problemas anteriores se refactorice en gran medida. Este es quizás un ejemplo extremo, sin embargo, muestra cómo los números de problema en los comentarios en el código pueden resultar bastante inútiles.
Si pudiera garantizar que la situación que acabo de describir nunca sucedería, todavía argumentaría que el número del problema en sí sigue siendo bastante inútil sin una descripción de qué se trata el problema, y, sin embargo, toda esta información realmente pertenece a su sistema de seguimiento de problemas y debería ser duplicado. Un mejor lugar para anotar el número de problema sería en su sistema de control de versiones como comentario de confirmación. La ventaja es que puede comparar versiones y ver los cambios en el código relacionados con un problema específico, mientras que el número de problema en sí mismo le proporciona el identificador necesario si desea revisar el motivo del cambio en el código.
Con todo esto en mente, sugeriría que no es realmente una buena práctica como tal agregar números de problemas a los comentarios dentro de su código.
Creo que es una buena práctica referirse a un tema para leer más, mientras da una breve explicación en el comentario en sí.
Generalmente solo agrego comentarios si hay algo sutil o poco intuitivo en ese código. Dado que algunos problemas sutiles no se pueden explicar por completo en unas pocas líneas, y no quiero agregar docenas de líneas de comentarios, agregaría un breve comentario que describe lo que esto está tratando de lograr, y me referiré al problema para detalles.
Por ejemplo:
// Verify MAC before checking the padding, to avoid padding oracle attacks
// See issue 123 for details
Donde el problema 123 describe cómo podría ser ese ataque y por qué el nuevo código es inmune al ataque.
O:
// Using foo's algorithm here, since it fits out usage pattern best
// Check issue 345 for a discussion of possible algorithms, and why foo was chosen.
El principal problema al poner números de problema en su fuente es que ahora tiene una referencia externa. Por lo tanto, debe asegurarse de no perder el problema.
Incluir el número de problema en los mensajes de confirmación puede ser muy útil cuando su código fuente está conectado con una integración continua. Las aplicaciones como TeamCity extraerán esa información y permitirán mejores informes.
Con lo anterior dicho, no estoy 100% seguro de que se extraiga de los comentarios del código. La inclusión de números de problema en el código funciona bien si los números de problema son persistentes (por ejemplo, no cambia los rastreadores de problemas) y no tiene muchos problemas para un proyecto determinado.
Probablemente sea más útil si describe el problema y la solución para que el próximo desarrollador no necesite buscar el número del problema. El compilador o minificador solo eliminará sus comentarios antes de que el código se publique en la naturaleza, por lo que no debería haber ningún impacto en el resultado final.