¿Es un "comentario divertido" una mala práctica o no? [cerrado]

Quiero preguntarle si agregar algunos "huevos de pascua" en la documentación original no es profesional o no. Probablemente usted ha leído el Stackoverflow sondeo para comentarios divertidos en una fuente de documentación, y se han topado personalmente en muchas de estas cosas durante mi trabajo, incluyendo gracioso (o no) cosas en documentación de la API pública (por ejemplo, esta débil BZZZTT !! 1! Lo en la documentación pública de Android, puedo dar al menos una docena más de ejemplos).

No puedo llegar a una opinión final por mí mismo, porque tengo argumentos contradictorios por mí mismo.

Argumento profesional:

• Puede animar a alguien y hacer que su día sea más divertido / productivo. La mayor parte del código fuente no necesita ser comentada de todos modos (si el proyecto se realiza correctamente), porque el método específico (por ejemplo) se explica por sí mismo, o si es una pila de código extraño extraño, no puede explicarse de manera significativa, para que un chiste gracioso no dañe la posible información que puede obtener del documento.

Argumento contras:

• Si está muy concentrado / frustrado, lo último que necesita es la broma estúpida de alguien, en lugar de brindarle la información que necesita sobre la parte del código documentado, puede hacerlo sentir aún más frustrado. Y la idea de cómo sería la documentación si todos comenzaran a hacerlo es horrible. Además, el tipo que escribe el chiste puede ser el único que piensa que es divertido / interesante / vale la pena perder el tiempo para leerlo.

¿Qué piensas?

Creo que los comentarios divertidos pierden tiempo: tiempo perdido para escribir, tiempo perdido para leer, tiempo perdido para mostrar a sus colegas el comentario divertido que (casi siempre) es simplemente desconcertante, etc.

Pero ... en realidad, nadie trabaja al 100% todo el día todos los días (sitios como este estarían vacíos si lo hiciéramos) y el humor genuino rompe el día y ayuda a mantener la moral.

Todavía votaría en contra simplemente porque cada comentario 'gracioso' que he leído puede haber sido muy gracioso en ese momento, pero aún no he visto uno que sea realmente gracioso, la mayoría son simplemente desconcertantes o son profundos -broma.

Si los comentarios divertidos fueran realmente divertidos, cambiaría de opinión. Pero una vez que fomentas bromas, ¿fomentas palabrotas, insultos o malicia?

Soy un gran fanático de los comentarios graciosos .

Siempre debe ser profesional en sus comentarios, pero algo de humor no matará al lector.

Especialmente si el lector es miembro de su equipo.

Lo que más me disgusta son los desarrolladores que se toman demasiado en serio. Creo que deberíamos divertirnos en el trabajo, o el trabajo no merece la pena.

Si tiene significado, está bien ser divertido. Explicar algo en un comentario de una manera divertida está bien. Sin embargo, si solo es algo divertido y no contiene ningún valor real como comentario, eso es simplemente molesto. Siempre tenga en cuenta que la razón de los comentarios es hacer que el mantenimiento sea más eficiente. El humor no tiene que entrar en conflicto con eso, pero podría hacerlo si no se hace adecuadamente.

El código está destinado a leer ... muchas veces.

¿Cuántos chistes sabes que son divertidos después de la centésima cuenta?

Los comentarios graciosos son geniales.

• Le da una vibra positiva a su código aparentemente aburrido.
• Si tienes tu tiempo correcto, explica mucho mejor que un comentario aburrido normal. Por "sincronización" aquí me refiero a la relevancia para el código debajo del comentario.
• Muchos recordarán su código porque las emociones tienen un lugar mejor en la memoria (humana). Este es un gran truco si quieres que más chicos trabajen contigo en un proyecto de código abierto.
• Generalmente útil en las revisiones. Hace que su código sea mucho más soportable. Por supuesto, primero debes concentrarte en escribir un buen código. Siento que cuando uno confía en el código que escribe, los comentarios divertidos son solo un efecto secundario.

Simplemente no seas gracioso como este chico ;)

Aquí hay uno que escribí a las dos de la mañana ("DQ" son las iniciales de mi compañía):

// Twas the night before go-live and all through DQ
// the devs were all crying and yes, this means you.
// Keys had been saved with both hyphens and 'scores
// which left this programmer with finger pad sores.
// The solution I crafted, you'll likely find lacking:
// to OR them together with judicuous hacking.

$hyphenated = str_replace('_','-',$data_type_key);
$underscored = str_replace('-','_',$data_type_key);
// (and then see line 46)

Si estuviera revisando su código fuente frente al cliente, ¿se sentiría avergonzado?

Ninguna de las respuestas actuales parece tener eso en cuenta. Algunos clientes no tienen sentido del humor y tomarán los chistes como un indicador de que no se toma en serio su trabajo. Inferirán que eres descuidado con tu trabajo.

Los comentarios divertidos de código a veces pueden ser poco profesionales e inapropiados.

Más allá de lo que ya se dijo, si está trabajando en un equipo internacional, es posible que algunos de sus colegas extranjeros no entiendan el chiste, ya sea por algunas referencias culturales locales o por el juego de algunas palabras que no entiende alguien para quien el inglés no es el idioma nativo. . Lo mismo se aplica para proyectos de código abierto.

Si es eficiente y no pierde el tiempo de los lectores (en lectura / comprensión), entonces no veo ningún problema con un poco de humor.

Al igual que los chistes en el mundo real, si los haces todo el tiempo no es divertido, ni productivo, ni profesional. Pero hay una hora y un lugar para todos los chistes, y hay una hora y un lugar en el código. Al igual que en el mundo real, es saber dónde, cuándo y cómo hacer el chiste.

Depende, para las tareas en la universidad, casi siempre hacía comentarios divertidos, ya que sabía que nunca se usarían y es solo una tarea.

Para proyectos más serios, todavía los usaría aquí y allá, pero no tan frecuentes, por lo que es molesto o difícil de entender, desafiando el propósito del comentario.

Recuerdo que hice un poco de programación web, donde tuve que esquivar incompatibilidades del navegador y fallas extrañas. A veces terminaba en comentarios llenos de ira y odio en los .jsarchivos.

Mi regla básica es: si es algo obvio lo que hace la sección de código, ¡LOS COMENTARIOS DIVERTIDOS SE ENCIENDEN!

Si el código es tan oscuro y confuso como el infierno (como la " clase en línea "), será mejor que use comentarios que me entenderé en un par de días ...