Mi cliente quiere el 25% de los comentarios en mi proyecto actual, ¿cómo reaccionar? [cerrado]

96

desarrollador junior aquí.

Actualmente estoy trabajando solo en una aplicación web para un gran cliente de mi empresa. Comencé el mes pasado. El cliente desea al menos el 25% de los comentarios en cada uno de sus proyectos de software.

Verifiqué el código de las aplicaciones anteriores y aquí están mis observaciones:

  • cada archivo comienza con un bloque de comentarios (paquete, fecha de la última actualización, nombre de mi empresa y copyright)
  • todas las variables están comentadas con sus nombres // nameOfCustomer public String nameOfCustomer

  • todos los captadores y definidores están comentados

  • muy pocos comentarios útiles

Parece que los desarrolladores simplemente hacen tantos comentarios como pueden para alcanzar ese umbral del 25%, independientemente de la calidad y la utilidad. Mi compañía me dice que "lo hacemos como el cliente lo quiere".

No hablé directamente con el cliente sobre esto. Aquí están mis argumentos hasta ahora:

  • líneas inútiles para leer y escribir (pérdida de tiempo)
  • los comentarios a veces no se actualizan (fuente de confusión)
  • es menos probable que los desarrolladores utilicen o confíen comentarios realmente útiles

¿Cuál es su consejo sobre este tema? ¿Cómo debo manejar la situación?

    
pregunta Robin_ 05.03.2018 - 22:52
fuente

12 respuestas

114

Todas las demás respuestas y comentarios aquí realmente me hicieron pensar, porque son muy contrarios a mi primera reacción y tan contrarios a la actitud que he visto en mis compañeros de trabajo. Así que me gustaría describir un enfoque alternativo, aunque solo sea por ser la voz disidente .

El principio guía de esta respuesta es: "Deleitar al cliente". Deleitar al cliente no solo significa satisfacer sus expectativas; Significa comprender sus solicitudes tan profundamente que puede interpretar lo que dicen de la manera en que lo dicen, y cumplir más allá de lo que piden. Otras respuestas parecen estar guiadas por el principio de cumplimiento malicioso, que me parece abominable; y además, es una práctica comercial cuestionable, ya que es una mala manera de conseguir clientes habituales.

Para mí, cuando escucho al cliente decir: "Quiero un 25% de comentarios", ese es el comienzo de un diálogo. Para mí está claro que la implicación aquí es "Quiero un montón de texto descriptivo, para que los recién llegados a este código base puedan ponerse en marcha rápidamente", no "quiero que agregue aleatoriedad en una determinada categoría sintáctica" como otras respuestas Parece que lo están tomando. Y tomaría esa solicitud seriamente, y tenía la intención de escribir muchos comentarios descriptivos y útiles, orientar a los recién llegados a la estructura del código, señalar decisiones de ingeniería sorprendentes y describir el razonamiento que surgió, y dar un alto nivel de inglés. Descripciones de secciones de código complicadas (incluso si no tienen sorpresas). Esta intención y comprensión es el punto de partida de la discusión, es decir, antes de que empecemos a hablar. Para mí, la implicación de la solicitud es tan clara que ni siquiera necesita esa aclaración; pero si no está claro, ¡por supuesto que debería consultar con ellos!

Bien, entonces, ¿a dónde va el diálogo si ese es el punto de partida? La siguiente parte del diálogo es así:

  1. Espero que este sea un esfuerzo adicional serio, posiblemente en una segunda fase del proyecto, que está más allá de la producción de la herramienta que les interesa trabajar. Pueden transcurrir varios minutos de discusión para discutir este proceso y por qué es un trabajo adicional, pero lo omitiré aquí porque, como programador profesional, espero que sepa lo difícil que es hacer el bien. comentarios.
  2. "Un esfuerzo adicional serio" significa que podemos necesitar un presupuesto de mayor tiempo y un mayor presupuesto monetario; o es posible que tengamos que reducir el presupuesto de funciones; o es posible que tengamos que comprometer la cantidad y calidad de los comentarios. Esta parte va a ser un poco de una negociación. Pero en mi opinión, debe ser muy directo con los costos de hacer este trabajo adicional y asegurarse de que sea una característica tan importante para el cliente que esté dispuesto a asumir estos costos. Y si lo son - ¡genial! Obtienes tiempo y dinero extra, y ellos reciben comentarios de alta calidad. Todo el mundo gana. Y si resulta que la función de comentarios no es tan importante para ellos que está dispuesta a perder la capacidad de cambiar los widgets o está dispuesta a dejar que la fecha límite llegue a finales de Granuary, 20x6, entonces todos ganan nuevamente: obtienen el producto que obtienen. desea, y no tiene que gastar el esfuerzo adicional necesario para crear comentarios de alta calidad.

Aquí es donde creo que el diálogo no debe ir:

  1. No amenace al cliente con comentarios de baja calidad. Permítales que lo ayuden a elegir el nivel de esfuerzo que desean gastar y que están dispuestos a pagar. No les prometa comentarios del 25% y luego infórmeles que tiene la intención de cumplir con esta promesa generando aleatoriedad automáticamente una vez que se haya construido el proyecto.
  2. No escondas tus planes. No les prometas comentarios del 25%, y luego genera automáticamente aleatoriedad sin decirles que eso es lo que vas a hacer. Cuando se dan cuenta (no si), ambos pierden mucho tiempo: no están contentos con el producto que recibieron, y usted tiene un boca a boca negativo.
  3. No intentes convencerlos de que no quieren comentarios. Ellos claramente quieren comentarios. Discuta las compensaciones de varios enfoques: ¡sí! Discuta formas alternativas de hacer que el nuevo código base sea amigable: ¡sí! Dígales que no saben lo que quieren: eh, no. Quieres trabajar con ellos para obtener lo que quieren; así que entienda qué es eso y descubra cuál es la mejor manera de entregárselo en un presupuesto que aprueben, priorizando las características que más les interesan si los recursos que tienen son insuficientes.
  4. No hagas excusas sobre lo difícil que es escribir comentarios. Escribir código es difícil; el código de depuración es difícil; Escribir comentarios es difícil. Si fuera fácil, no estarían contratándote. Simplemente omita las quejas y vaya directo al punto que les interesa, es decir, cómo les afecta el esfuerzo adicional requerido.
respondido por el Daniel Wagner 06.03.2018 - 14:48
fuente
83

El cliente es el rey. Así que como contratista deberá cumplir con lo que el cliente haya definido como estándar de calidad. O te arriesgas a estar fuera.

Dicho esto, importa mucho cómo se definen los estándares de calidad (aquí malos):

  • Estándares de calidad contractuales: el código entregado debe cumplir, o de lo contrario es un incumplimiento de contrato. Sin elección.

  • Estándares de calidad corporativos formales: incluso si funciona a la perfección, el código que no cumple se considerará de mala calidad por tanta gente, que será viejo antes de que los haya convertido a todos en una mejor práctica. Peor aún: se pueden usar herramientas bien conocidas para automatizar y legitimar tales métricas de calidad (por ejemplo, sonar cube ). Casi no hay elección.

  • Criterios ad-hoc definidos por un par de personas en el cliente. Aquí podría participar en la discusión. Hay esperanza :-)

En este último caso, podría haber cierta flexibilidad, y usted podría tratar de hacer el punto diplomáticamente. Aquí algunos argumentos que hablan en contra de los criterios del cliente:

  • Problema de productividad: la codificación se realiza dos veces (una vez en inglés y una vez en código).
  • Problema de precisión: si se realizan cambios en el código, deben hacerse en los comentarios, o los comentarios podrían volverse inútiles.
  • Problema de refactorización: como herramienta de refactorización no procesa los nombres de las variables en los comentarios.
  • Problema de riesgo: la ambigüedad (u obsolescencia) de los comentarios podría generar confusión y riesgo de aumentar los errores.
  • La cantidad no es calidad
  • Esta divertida colección de comentarios inútiles en StackOverflow .
  • Este artículo que argumenta que una proporción alta de comentarios podría igualar Ser el signo de un olor de código.

Pero en lugar de hablar en contra de lo malo y confrontar al cliente, puede ser que simplemente puedas promover mejores enfoques:

  • Código limpio (sugiera el libro a su cliente: hay una sección convincente dedicada a los comentarios y al código de auto-documentación).
  • Práctica de documentación: las cosas más difíciles de comprender y, por lo tanto, la información más valiosa, como por ejemplo, la relación y la interacción entre clases, ¿está mejor documentada en un documento separado (por ejemplo, en una imagen UML en lugar de 1000 palabras de comentario? )

Si el cliente aún no está convencido, podría proponer una alternativa experimental, utilizando herramientas para generar documentación automáticamente con comentarios, como javadoc o doxygen . Proponga con ello cambiar el enfoque de la cantidad (25% de código) a la calidad (generar un javadoc comprensible).

    
respondido por el Christophe 06.03.2018 - 00:01
fuente
18
  

El cliente desea al menos el 25% de los comentarios en cada uno de sus programas.   proyectos.

¿El cliente realmente desea el 25% de los comentarios o su cliente desea que su código sea lo más descriptivo posible?

En mi humilde opinión, el cliente sabe lo que quiere, pero no lo que necesita. Como un cliente no es un desarrollador en sí mismo y recibe comentarios de sus propios trabajadores / clientes, su cliente solo ve la parte superior del iceberg.

Supongo que su cliente tiene algunos pseudo-conocimientos y quiere que el código esté bien documentado y sea fácil y económico de mantener, y la herramienta para esto son los comentarios (en su opinión).

Intente hablar con él y prepare algunos fragmentos de código con un código bien escrito que se explique a sí mismo y otro escrito mal con comentarios. Sólo unas pocas líneas. Muéstrelo si es necesario y utilícelo como imagen para sus palabras.

Hable con su cliente / supervisor / lo que sea e intente decirles los principios modernos del control de versiones (no es necesario que haga comentarios al principio del archivo) y limpie el código (recomiendo el libro también) y, por lo tanto, resulta un código autoexplicativo.

Tal vez, si puede mostrarlo lo suficientemente bien y hacer que su cliente entienda que quiere un código limpio, no solo comentarios, usted y su equipo pueden escribir un código mejor (con mucho menos comentarios) y demostrar de inmediato que usted es un buen desarrollador vale la pena mantener.

    
respondido por el Chrᴉz 06.03.2018 - 08:53
fuente
12

Esto me recuerda esas respuestas tontas de desbordamiento de pila que constan de una línea seguida de, literalmente, "texto aquí para llegar al límite de caracteres mínimo".

Cuando esto sucede, se podrían argumentar que dos grupos de personas tienen la culpa:

  1. Las personas que ponen el límite: claramente es excesivo e impide que las personas envíen información debidamente formada sin agregar ruido artificial

  2. Las personas que enviaron información que no se formó correctamente, luego agregaron ruido artificial cuando el sistema les pidió que agregaran más sustancia real

A veces, una pregunta será simple sobre y sobre el tema, y no hay mucho más que decir que unas pocas palabras. Sin embargo, esto es extremadamente raro. En casi todos los casos, hay mucho más sustancia que decir. Si nada más, debería ser cegadoramente obvio que la forma de sortear una restricción de caracteres no es simplemente volcar ruido aleatorio en tu publicación.

Esta situación de comentarios que estás enfrentando es casi la misma. Sus desarrolladores han recibido una solicitud de comentarios y lo han implementado mediante el lanzamiento de ruido aleatorio en su código. Documentar los nombres de las variables, justo al lado de la declaración de las variables, es vandalismo . Eso nunca debería haber ocurrido.

"Pero, ¿de qué otra manera podemos llegar al 25%?" Al escribir los comentarios reales de la sustancia. Use más palabras, mejores palabras, las mejores palabras para documentar el efecto de las funciones. Amplíe sus explicaciones. Describa los casos de borde con más detalle.

Sin embargo, volviendo al punto original, el cliente también es parcialmente culpable aquí, porque "25% del código fuente" es extremadamente arbitrario. Sin embargo, en última instancia, ellos son el cliente, así que aprovéchalo. Pero quiero decir "mejor". No es "lo peor", como ha estado sucediendo hasta ahora.

    
respondido por el Lightness Races in Orbit 06.03.2018 - 15:08
fuente
5

No sé cuál es el gran problema con este requisito.

Simplemente por doxygenation básico de su código, probablemente ya esté en aproximadamente el 10%. Y tomemos otro 5% de los comentarios que han escrito (algunos escriben más, pero el 5% parece una estimación conservadora si no ha hecho un voto de silencio). En este punto, es alrededor del 15% (sí, sí, lo sé, el 5% del 90% es menos del 5%, no lo hagas). Si su doxygen es inferior al 10%, quizás sus métodos sean muy largos; Por lo general, es una buena idea dividirlos en otros más pequeños (en su mayoría privados / protegidos), o usar clases de ayuda más genéricas, etc.

Ahora, para el resto del texto de comentario, ponga las consideraciones de diseño y los escenarios de uso en los comentarios de nivel de clase / archivo. Tenga algunas tablas o ASCII-art (o código doxygen que genere cosas de aspecto agradable cuando se renderiza). No sé, por supuesto, de qué trata su proyecto, pero creo que puede hacer esto sin comentarios ficticios (aparte de la placa de repetición de la doxigenación) y llegar a algo cercano al 25%.

Si es solo, digamos, 20% y no 25%. Estoy seguro de que el cliente simplemente dio ese número como algo arbitrario, y estará de acuerdo con eso. De todos modos, hable con ellos para discutir lo que deben incluir los comentarios; y muéstrales un ejemplo de archivo comentado para ver si están satisfechos. Si lo son, eso es todo, si piensan que falta algo, le dirán lo que falta. No le dirán "No podemos sugerir ningún comentario adicional, pero queremos que agregue algunos".

PS: mira el código de los contenedores de Java estándar para ver cómo puedes alcanzar, oh, 70% o menos ...

    
respondido por el einpoklum 06.03.2018 - 19:26
fuente
5

Tener un 25% de comentarios en su código es un excelente objetivo, y hace feliz al cliente. Ahora, escribir 25% de comentarios de relleno como "i + = 1; // aumentar i en 1" debería estar debajo de ti, así que tómate tu tiempo, escribe comentarios útiles y disfruta de la sensación de que realmente te pagan por hacer algo que debes hacer de todas formas.

    
respondido por el gnasher729 06.03.2018 - 20:33
fuente
4

Todos sabemos que esto es un requisito de mierda. La pregunta interesante aquí es

  

¿Cómo reaccionar?

Soy un gran creyente en hacer que los problemas sean visibles. Aquí usaría el hecho de que el dinero habla.

Pídeme que haga esto y le aseguro que agregará un 1% a mi oferta. Ah, pero se agregará un 20% a las futuras ofertas de mantenimiento.

Solo una vez que preguntan, ¿por qué les enseñaré que el objetivo de los buenos nombres es evitar la necesidad de comentar?

Como alternativa, propondré la creación de documentación destinada a obtener un programador de mantenimiento con un conjunto definido de calificaciones asumidas para acelerar las ideas detrás del proyecto. O claro, podría darte un 25% de comentarios. Depende de usted.

    
respondido por el candied_orange 06.03.2018 - 16:40
fuente
3

Sí, entiendo tu frustración con la regla tonta. He leído muchos programas con comentarios inútiles como

x = x + 1; // add 1 to x

Y me digo a mí mismo, ¡Así que eso es lo que significa un signo más! Wow, gracias por decirme, no lo sabía.

Pero dicho eso, el cliente está pagando la factura. Por lo tanto, les das lo que quieren. Si trabajara en un concesionario de automóviles y un cliente me dijera que quería una camioneta, no discutiría con él si realmente necesita una camioneta y le preguntaría qué espera transportar. Le vendería una camioneta.

Bueno, hay ocasiones en que lo que los clientes dicen que quiere y lo que realmente necesita están tan lejos que trato de discutir el asunto con él, tal vez convencerlo de que acepte algo más racional. A veces esto funciona, a veces no funciona. Al final, si no puedo cambiar de opinión, le doy lo que quiere. Si regresa más tarde y dice: "Oh, eso realmente no cumplió con mis requisitos comerciales, entonces podemos cobrarle más por hacer lo que le dijimos que hiciera la primera vez". La cantidad de dinero que usted puede negociar con el cliente depende de su confianza en su experiencia, de cómo su contrato con usted se adapta a la organización y, francamente, de cuán optimistas son.

Sería un caso muy raro en el que, suponiendo que dependiera de mí, perdería un contrato porque pensé que los requisitos no estaban bien concebidos.

Tenga en cuenta que las personas con las que su empresa está negociando pueden o no ser las que inventaron esta regla del 25%. Podría ser una regla impuesta desde arriba hacia arriba.

Veo cinco respuestas posibles:

Uno. Convenza a su jefe o a quien esté negociando con el cliente para discutir sobre esto. Lo más probable es que esto no logre nada, pero puedes intentarlo.

Dos. Se niegan a hacerlo. Es probable que esto lo despida, o si la compañía está de acuerdo con usted, puede perder el contrato. Esto parece improductivo.

Tres. Escriba comentarios inútiles para llenar el espacio, el tipo de comentarios que simplemente repiten lo que está en el código y que cualquier programador capaz de modificar el código podría ver en 2 segundos. He visto muchos comentarios como este. Hace años trabajé para una empresa en la que debíamos colocar bloques de comentarios delante de cada función que enumeraba los parámetros, como:

/*
GetFoo function
Parameters:
  name: String, contains name
  num: int, the number
  add_date: date, the date added
Returns:
  foo code: int
*/
int GetFoo(String name, int num, Date add_date)

La objeción de que dichos comentarios son una carga de mantenimiento porque tiene que mantenerlos actualizados no es válida. No hay necesidad de mantenerlos actualizados porque ningún programador serio los verá nunca. Si hay alguna duda al respecto, asegúrese de dejar claro a todos los miembros del equipo que los comentarios inútiles y redundantes deben ignorarse. Si desea saber cuáles son los parámetros de una función o qué hace una línea de código, lea el código, no mire los comentarios inútiles.

Cuatro. Si va a agregar comentarios sin valor redundantes, tal vez valga la pena escribir un programa para generarlos. Algo de una inversión por adelantado, pero podría ahorrar un montón de escribir en el camino.

Cuando empecé en este negocio, una empresa para la que trabajaba usaba un programa que se anunciaba como "¡Escribe tu documentación para ti! ¡Documentación completa para cada programa!" El sistema requería que le asignáramos a todas las variables nombres esencialmente sin significado y luego tuviéramos una tabla con un nombre significativo para cada variable, por lo que básicamente lo que hizo la "documentación automática" fue reemplazar el nombre sin significado que nos obligó a usar con un nombre significativo. Así que, por ejemplo, esto funcionó con COBOL, tendría una línea en su programa que decía

MOVE IA010 TO WS124

y generarían una línea de "documentación" que decía

COPY CUSTOMER NAME IN INPUT RECORD TO CUSTOMER-NAME IN WORKING STORAGE

De todos modos, seguramente se podría escribir un programa para generar documentación igualmente sin valor con bastante facilidad. Lee una línea como

a=b+c

y genera el comentario

// add b to c and save result in a

Etc.

Cinco. Haz lo mejor de la regla tonta. Trate de escribir comentarios útiles y significativos. Hey, podría ser un buen ejercicio.

Por cierto, puedo añadir que siempre se puede jugar con la métrica.

Recuerdo una vez que un empleador dijo que iban a comenzar a medir la productividad de los programadores por la cantidad de líneas de código que producíamos por semana. Cuando nos dijeron esto en una reunión, dije: ¡Genial! Puedo aumentar mi puntuación fácilmente. No más escritura

x=x+4;

En su lugar escribiré:

x=x+1;
x=x+1;
x=x+1;
x=x+1;

Loops? Olvídalo, copiaré y pegaré el código diez veces. Etc.

Así que aquí, si van a contar líneas de comentarios, haga que cada línea sea corta y continúe con la idea en la siguiente línea. Si hay un cambio en lo que sucede en los comentarios, no actualice el comentario existente. Ponga una fecha en él, luego copie el texto completo y escriba "Actualizado" y una nueva fecha. Si el cliente lo cuestiona, dígales que pensó que era necesario mantener el historial. Etc. etc.

    
respondido por el Jay 06.03.2018 - 17:25
fuente
2

Las métricas arbitrarias parecen ser un hecho de la vida en muchos proyectos ...

Esto se ve a menudo en requisitos estúpidos, como una complejidad ciclomática máxima que conduce a un código más complejo, porque las funciones se dividen innecesariamente para garantizar el cumplimiento, o los archivos se dividen porque superan cierta longitud arbitraria de SLoC

Los comentarios deben agregarse al código, y explicar lo que está sucediendo (¡y no solo repetir el código!).

Dicho esto, si esto es lo que quiere su cliente y su empresa ha aceptado proporcionarle, a menos que su Gerente de control de calidad desarrolle una dosis de sentido común, estará atascado.

    
respondido por el Andrew 06.03.2018 - 15:05
fuente
2

A corto plazo no hay nada que puedas hacer realmente. Acompáñalo.

También deberías ignorar todas las ideas estúpidas que estoy viendo en este hilo sobre protestas pasivas agresivas y bromas tontas dentro del código.

Una vez que haya desarrollado una relación de confianza con el cliente, estarán en mejor posición para escuchar su razonamiento; podría encontrar que esta es una demanda tonta de una persona que alguna vez fue influyente y que tiene muy poco apoyo en -casa.

Bajo ninguna circunstancia debe ir en su contra sin el permiso del cliente.

    
respondido por el gburton 06.03.2018 - 21:00
fuente
2

Estoy decepcionado por la falta de imaginación mostrada por mis compañeros programadores aquí.

Me parece que el cliente hizo algunas investigaciones. Es posible que haya leído en alguna parte que el código de calidad generalmente contiene aproximadamente el 25% de los comentarios. Obviamente, a él le preocupa / le preocupa el mantenimiento en el futuro. Ahora, ¿cómo hace eso concreto en un documento de requisitos que debe estar vinculado a un contrato? Eso no es fácil. Incluso puede ser imposible. Sin embargo, quiere asegurarse de que obtendrá valor por su dinero, por lo que enumera algunos indicadores de calidad.

Eso no me suena estúpido o ridículo en absoluto. Las personas que escribieron los requisitos probablemente no son programadores. Es posible que hayan tenido una mala experiencia con un proyecto anterior. Sus muchachos de mantenimiento se quejan: "¡Nada de esta mierda está documentado!". Está sonando en los oídos a medida que escriben nuevos requisitos para el próximo proyecto.

Si realmente desea documentar su código y proporcionar un contexto para la cuadrilla de mantenimiento, este requisito se cumplirá automáticamente. ¡Así que no seas un chiflado!

Al final, sea 21% o 29%, a nadie le importará. El desarrollador revisará tus cosas por un desarrollador independiente y él entenderá mejor lo que hiciste.

    
respondido por el Martin Maat 06.03.2018 - 22:57
fuente
0

He conocido a muchos programadores que no entienden cómo existen personas que actualmente no trabajan en este proyecto.

Para ellos todo lo que saben, ES conocido por todos.

Si alguien no sabe TODO lo que sabe actualmente, entonces esas personas son "idiotas" para ellos.

Con este estándar, puedes forzar a las personas a entrar en un habbit para escribir comentarios.

Es posible que escriban comentarios inútiles el 99% del tiempo, pero a veces en realidad escriben una de las cosas que "TODOS SABEN", y alguien nuevo en el equipo podría no pasar 16 horas buscando un error. ya resuelto, pero luego se deshizo por otra razón) que hubiera sido obvio con un comentario en ese punto en el código.

Tener comentarios en líneas con errores no obvios también puede ayudar a evitar que los futuros programadores rompan completamente un programa por accidente (especialmente cuando la parte "estar roto" no es evidente cuando se realiza una prueba rápida).

    
respondido por el HopefullyHelpful 07.03.2018 - 01:26
fuente

Lea otras preguntas en las etiquetas