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

desarrollador junior aquí.

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

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

• cada archivo comienza con un bloque de comentarios (paquete, fecha de última actualización, nombre de mi empresa y derechos de autor)

• todas las variables se comentan con sus nombres // nameOfCustomer public String nameOfCustomer

• todos los captadores y colocadores son comentados

• muy pocos comentarios útiles

Parece que los desarrolladores solo colocan tantos comentarios como pueden para alcanzar ese umbral del 25%, independientemente de la calidad y la utilidad. Mi empresa 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 usen o confíen en comentarios reales útiles

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

Todas las otras respuestas y comentarios aquí realmente me dejaron sin aliento, porque son muy contrarios a mi primera reacción y muy contrarios a la actitud que he presenciado en mis compañeros de trabajo. Entonces, me gustaría describir un enfoque alternativo, aunque solo sea por ser la voz disidente .

El principio rector de esta respuesta es "deleite al cliente". Deleitar al cliente no solo significa cumplir con sus expectativas; significa comprender sus solicitudes tan profundamente que puede interpretar lo que dicen en la forma en que lo dicen, y entregar más allá de lo que piden. Otras respuestas parecen estar guiadas por el principio de cumplimiento malicioso, que me parece aborrecible; Además, es una práctica comercial cuestionable, ya que es una mala forma 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 mucho texto descriptivo, para que los recién llegados a esta base de código puedan comenzar a funcionar rápidamente", no "Quiero que agreguen aleatoriedad en una determinada categoría sintáctica" como otras respuestas parece estar tomándolo. Y tomaría esa solicitud en serio, y me propongo escribir muchos comentarios descriptivos y útiles, guiando a un recién llegado a la estructura del código, señalando decisiones de ingeniería sorprendentes y describiendo el razonamiento que entraña, y dando inglés de alto nivel. 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, eso es incluso 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, debe 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. Esperaría que esto sea un esfuerzo adicional serio, posiblemente en una segunda fase del proyecto, que va más allá de la producción de la herramienta que les interesa trabajar. Puede haber varios minutos de discusión para discutir este proceso y por qué es un trabajo adicional, pero voy a omitirlo aquí porque, como programador profesional, espero que sepas lo difícil que es hacer buenos comentarios.
2. "Un esfuerzo adicional serio" significa que podemos necesitar un presupuesto a más largo plazo y un presupuesto monetario mayor; o es posible que necesitemos reducir el presupuesto de funciones; oEs posible que necesitemos comprometer la calidad y cantidad de comentarios. Esta parte va a ser un poco de negociación. Pero en mi opinión, debe ser muy directo sobre 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 reciben comentarios de alta calidad. Todos ganan. Y si resulta que la función de comentarios no es tan importante para ellos que están dispuestos a perder la capacidad de mover widgets o dejar que la fecha límite se deslice hasta finales de Granuary, 20x6, entonces todos ganan de nuevo: obtienen el producto que desea y no tiene que gastar el esfuerzo adicional que se necesita para crear comentarios de alta calidad.

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

3. No amenace al cliente con comentarios de baja calidad. Permita 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 después de que se construya el proyecto.
4. No escondas tus planes. No les prometa comentarios del 25%, y luego genere aleatoriedad automáticamente sin decirles que eso es lo que va a hacer. Cuando se dan cuenta (no si), ambos pierden a lo grande: no están contentos con el producto que obtuvieron, y usted obtiene un boca a boca negativo.
5. No intentes convencerlos de que no quieren comentarios. Claramente quieren comentarios. Discuta las compensaciones de varios enfoques: ¡sí! Discuta formas alternativas de hacer que la base de código sea nueva: ¡sí! Diles que no saben lo que quieren: eh, no. Desea trabajar con ellos para obtener lo que quieren; así que comprenda qué es eso y descubra la mejor manera de entregarles eso en un presupuesto que aprueben, priorizando las características que más les interesan si los recursos que tienen son insuficientes.
6. No inventes 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 te contratarían. Simplemente omita las quejas y diríjase directamente al punto que les interesa, es decir, cómo les afecta el esfuerzo adicional requerido.

El cliente es el rey. Por lo tanto, 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í deficientes):

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

• Estándares formales de calidad corporativa: incluso si funciona perfectamente, muchas personas considerarán que el código que no cumple es de mala calidad, por lo que serás viejo antes de convertirlos en una mejor práctica. Peor aún: se pueden utilizar herramientas bien conocidas para automatizar y legitimar tales métricas de calidad (por ejemplo, cubo de sonda ). Casi no hay elección.

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

En este último caso, podría haber cierta flexibilidad, y podría intentar aclarar 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 en inglés y otra 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 la 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 para aumentar los errores.
• La cantidad no es calidad
• Esta divertida colección de comentarios inútiles en StackOverflow .
• Este artículo argumenta que una alta proporción de comentarios podría incluso ser el signo de un olor a código.

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

• Código limpio (sugiera el libro a su cliente: hay una sección convincente dedicada a los comentarios y el código de autodocumentació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 e interacción entre clases, está mejor documentada en un documento separado (por ejemplo, en una imagen UML en lugar de 1000 palabras de comentarios).

Si el cliente aún no está convencido, puede proponer una alternativa experimental, utilizando herramientas que generen automáticamente documentación con comentarios, como javadoco doxygen. Proponga con ello cambiar el foco de la cantidad (25% del código) a la calidad (generar un javadoc comprensible).

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

¿El cliente realmente quiere el 25% de los comentarios o quiere 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 cierto pseudoconocimiento 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 por sí mismo, y otro mal escrito con comentarios. Solo unas pocas líneas. Muestre esto si es necesario y úselo como imagen para sus palabras.

Hable con su cliente / supervisor / lo que sea e intente decirles los principios modernos del control de versiones (sin necesidad de comentarios al comienzo del archivo) y el código limpio (también recomiendo el libro ) y, por lo tanto, el código que se explica por sí mismo.

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

Esto me recuerda esas tontas respuestas de Desbordamiento de pila que ves que consisten en una línea seguida, literalmente, de "un texto aquí para llegar al límite mínimo de caracteres".

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

1. Las personas que ponen el límite: claramente es excesivo y evita que las personas envíen su 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 solicitó agregar más sustancia real

A veces, una pregunta será simple 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. Por lo menos, debería ser cegadoramente obvio que la forma de sortear una restricción de caracteres no es simplemente volcar ruido aleatorio en su publicación.

Esta situación de comentarios que estás enfrentando es casi la misma. Sus desarrolladores han recibido una solicitud de comentarios y la han implementado volcando 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 sucedido.

"¿Pero de qué otra forma podemos llegar al 25%?" Al escribir comentarios reales de sustancia. Use más palabras, mejores palabras, las mejores palabras para documentar el efecto de las funciones. Expande tus explicaciones. Describa casos extremos con más detalle.

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

No sé por qué tanto alboroto con este requisito.

Con solo la oxigenación básica de su código, probablemente ya esté al 10% más o menos. Y tomemos otro 5% de los comentarios que han escrito para ustedes mismos (algunos escriben más, pero el 5% parece una estimación conservadora si no han hecho un voto de silencio). En este punto, es de alrededor del 15% (sí, sí, lo sé, 5% del 90% es menos del 5%, no toque). Si su oxígeno 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 del comentario, incluya consideraciones de diseño y escenarios de uso en los comentarios de nivel de clase / archivo. Tenga algunas tablas o arte ASCII (o código de doxygen que genere un aspecto más agradable cuando se procesa). No sé, por supuesto, de qué se trata su proyecto, pero creo que puede hacer esto sin comentarios falsos (aparte de la repetitiva de la oxigenación) y llegar a algo cercano al 25%.

Si es solo, digamos, 20% y no 25%, estoy seguro de que el cliente solo dio ese número como algo arbitrario, y estará bien con eso. De todos modos, hable con ellos para discutir lo que deben incluir los comentarios; y muéstreles un archivo comentado de ejemplo para ver si están contentos. Si es así, eso es todo, si creen que falta algo, te dirán lo que falta. No le dirán "No podemos sugerir ningún comentario adicional posible, pero aún queremos que agregue algunos".

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

Tener un 25% de comentarios en su código es un objetivo excelente y alegra al cliente. Ahora escribir 25% de comentarios de relleno de mierda 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.

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

¿como reaccionar?

Creo firmemente en hacer visibles los problemas. Aquí usaría el hecho de que el dinero habla.

Pídame que haga esto y le diré que eso agregará un 1% a mi oferta. Ah, pero agregará un 20% a cualquier oferta de mantenimiento futura.

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é crear 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.

Sí, entiendo tu frustración con la tonta regla. 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 que 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 dijera que quería una camioneta, no discutiría con él sobre si realmente necesita una camioneta y le preguntaría qué espera transportar. Le vendería una camioneta.

De acuerdo, hay momentos en que lo que los clientes dicen que quiere y lo que realmente necesita están tan separados 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. 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 satisfizo los requisitos de mi negocio, entonces podemos cobrarle más por hacer lo que le dijimos que hiciera la primera vez. Cuánto puede negociar con el cliente depende de cuánto confía en su experiencia, cómo su contrato con usted encaja con la organización y, francamente, cuán tacaños son.

Sería un caso muy raro donde, suponiendo que fuera por mí, perdería un contrato porque pensaba que los requisitos estaban mal concebidos.

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

Veo cinco posibles respuestas:

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

Dos. Negarse a hacerlo. Esto probablemente lo despedirá, o si la compañía está de acuerdo con usted, hará que pierda el contrato. Esto parece improductivo.

Tres. Escriba comentarios inútiles para llenar 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 donde se nos exigía 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 tales comentarios son una carga de mantenimiento porque hay que mantenerlos actualizados no es válida. No es necesario mantenerlos actualizados porque ningún programador serio los mirará. Si hay alguna pregunta al respecto, asegúrese de dejar en 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 redundantes sin valor, quizás valga la pena escribir un programa para generarlos. Algo de una inversión por adelantado, pero podría ahorrar un montón de tipeo en el futuro.

Cuando comencé en este negocio, una compañía para la que trabajaba utilizaba un programa que se anunciaba como "¡Escribe su documentación para usted! ¡Documentación completa para cada programa!" El sistema requería que le diéramos a todas las variables nombres esencialmente sin sentido y luego tener una tabla con un nombre significativo para cada variable, así que básicamente lo que hizo la "documentación automática" fue reemplazar el nombre sin sentido que nos obligó a usar con un nombre significativo. Entonces, 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, uno seguramente podría escribir un programa para generar documentación igualmente inútil con bastante facilidad. Lee una línea como

a=b+c

y generar el comentario

// add b to c and save result in a

Etc.

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

Ah, por cierto, puedo agregar que siempre puedes jugar la métrica.

Recuerdo que 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 puntaje fácilmente. No más escribir

x=x+4;

En cambio, escribiré:

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

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

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

Las métricas arbitrarias parecen ser una realidad en muchos proyectos ...

Esto a menudo se ve en requisitos tontos, 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 exceden cierta longitud de SLoC arbitraria

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 acordado proporcionarlo, a menos que su gerente de control de calidad desarrolle una dosis de sentido común, está estancado.

A corto plazo, no hay nada que puedas hacer realmente. Sigue con ello.

También debe ignorar todas las estúpidas ideas que veo en este hilo sobre protestas agresivas pasivas y bromas tontas dentro del código.

Una vez que haya desarrollado una relación de confianza con el cliente, estará en mejores condiciones para escuchar su razonamiento; es posible que se trate de una demanda tonta de una persona que alguna vez fue influyente y que tiene muy poco apoyo interno.

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

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

Me parece que el cliente investigó un poco. Es posible que haya leído en alguna parte que el código de calidad generalmente contiene alrededor del 25% de los comentarios. Obviamente, se preocupa / preocupa por el mantenimiento más adelante. Ahora, ¿cómo concreta eso en un documento de requisitos que se debe vincular a un contrato? Eso no es facil. Incluso puede ser imposible. Sin embargo, quiere asegurarse de obtener el valor de 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 sean programadores. Es posible que hayan tenido una mala experiencia con un proyecto anterior. Sus chicos de mantenimiento se quejan: "¡Nada de esta mierda está documentada!". Está sonando en los oídos mientras escriben nuevos requisitos para el próximo proyecto.

Si se toma en serio la documentación de su código y el contexto para la pandilla de mantenimiento, este requisito se cumplirá automáticamente. ¡Así que no seas un idiota al respecto!

Al final, ya sea 21% o 29%, a nadie le importará. El desarrollador hará que un desarrollador independiente revise tus cosas y comprenderá mejor lo que hiciste.

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, puede obligar a las personas a entrar en un hábito de escribir comentarios.

Pueden escribir comentarios inútiles el 99% del tiempo, pero a veces pueden escribir una de las cosas que "TODOS SABEN", y alguien nuevo en el equipo podría no pasar 16 horas buscando un error (algo que ya resuelto, pero luego se deshizo por otra razón) que habría sido obvio con un comentario en ese punto del 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 "interrumpida" no es obvia al hacer una prueba rápida).