Mi jefe quiere una explicación narrada en línea línea por línea de nuestro código

Se me ha pedido específicamente que brinde una explicación o comentario línea por línea (o según corresponda, por ejemplo, imagen por imagen, etc.) que mi jefe quiere poder leer y seguir.

Como no es programador, no puede seguir el código, por lo que quiere que todo esté traducido al inglés.

¿Se le ha pedido a alguien que haga esto antes?

He comentado todo el código fuente y he usado JSDoc para generar documentación completa de todas las funciones, variables, etc. e incluí un ejemplo de implementación y demostraciones de trabajo completas con comentarios en todo momento.

¿Hay algo más que pueda hacer para comentar el código para los no programadores?

Esta no es una solicitud razonable, ¿verdad?

ACTUALIZAR

Al final, logré explicar por qué no era un buen uso del tiempo hacer lo que estaba pidiendo. Es un tipo razonable, y simplemente no entendía lo que implica mi trabajo. Una vez que vio esta publicación, creo que comprendió rápidamente que no era una solicitud normal.

Proporcioné documentación que es adecuada para que la siga otro programador (JSDoc y comentarios en línea, así como algunas notas adicionales sobre cuestiones técnicas), y un diagrama de flujo muy amplio de la lógica principal del programa para que mi jefe lo siga.

Al final, todas las partes quedaron satisfechas y hemos seguido adelante.

¡No , no es una solicitud razonable!

HABLE CON ELLA , o haga que alguien más lo discuta, por todos los medios. Esa es una idea irracional, que aunque factible es tan costosa, nunca debería hacerse. Una descripción general de las funciones y subrutinas es razonable, pero "explicar" cada línea de código no lo es. Sería más efectivo para él aprender a leer el idioma en mano que hacerlo.

Lo siguiente que pedirá es traducir fórmulas matemáticas, o lo que sea, al texto en inglés. Aunque ciertamente es posible, eso introduce mucho margen para el error y la mala interpretación , y nunca debe hacerse. Al igual que el código de "traducción" al inglés.

¿Tienes documentos de diseño ? Esas son las explicaciones en inglés de lo que hace el código. Un gerente que no sea de programación no debería necesitar más que eso.

¿Hay un premio de microgerente del año? Parece que tu jefe merece una nominación. Alguien que cree que necesita una comprensión del código línea por línea, pero no quiere aprender a leerlo directamente, es tan perfecto como el microgerente como se puede imaginar.

Una ventaja de ser desarrollador es que la dificultad de comprender el código impide la microgestión más allá de cierto grado, al menos en el nivel de implementación detallado, al menos por parte de una administración no técnica, porque incluso el microadministrador más duro reconoce que son sobre su cabeza a ese nivel. Pero el genio de su jefe puede encontrar una manera de romper la cortina de silicio.

Y, como beneficio adicional, desperdicia una enorme cantidad de tiempo del desarrollador haciendo la traducción, incluso antes de que use la traducción al inglés para comenzar a sugerir varias mejoras (supongo que él sabe codificar mejor que los programadores, aunque no puede lea el código y podrá compartir su sabiduría tan pronto como alguien lo traduzca; de lo contrario, ¿por qué necesitaría que se traduje cada línea?).

Entonces, no, no es una solicitud razonable, y nunca antes había oído hablar de ella. Y siento por ti. Creo que todos deben comenzar a buscar otro trabajo en silencio, porque una vez que comience a usar la traducción de códigos como herramienta de administración, probablemente será un lugar brutal para trabajar (er, un lugar más brutal para trabajar).

En el lado positivo, ¿tal vez pueda obtener un nuevo antipatrón con el nombre de su situación? ¿Qué tal el antipatrón "Libro de frases húngaro sucio", después de la parodia de Monty Python donde un estanquero intenta comunicarse con alguien que no habla inglés usando un libro de frases húngaro que tiene traducciones cómicamente falsas?

Siéntate con él y háblale a través de 10 líneas del código. Explique cada detalle hasta que ambos estén de acuerdo en que él lo comprende en la medida en que él quería.

Tal vez esta experiencia es todo lo que está buscando: solo una impresión de cómo es su trabajo para usted y cómo se ve el software desde su punto de vista. Eso es algo bueno en mi libro.

Si después de esto, él todavía quiere que continúes, di: observa cuántas preguntas tuve que hacerte; imagínese si hubiera tenido que explicar todo esto sin poder hacer preguntas, ¿cómo podría haber sabido qué incluir y qué dejar de lado? ¿Cuánto tiempo hubiera llevado antes de que los resultados le fueran útiles? ¿Cuántas líneas quieres que haga de esta manera?

No creo que sea una solicitud razonable. El CÓDIGO FUENTE no debe leerse en inglés (ni en ningún otro idioma).

Tal vez teme que vayas a hacer que tu código haga algo que no aprueba o que conoce. Si ese es el caso, no creo que haya algo que pueda hacer al respecto. Tendrá que escribir la documentación o quizás convencerlo de que contrate a alguien para que audite su código.

Realmente es muy simple:

• Has sido contratado por tus habilidades como programador
• Su gerente no tiene estas habilidades
• Ergo, su gerente no debe esperar razonablemente poder entender completamente lo que hace.

He tenido una experiencia similar a esto en un trabajo anterior. Mi gerente era un contador (y, por lo tanto, estaba orientado a detalles de muy bajo nivel), y no entendía o realmente no confiaba en la programación. No podía comprender que ella, como persona no técnica, no debería esperar ser capaz de comprender los detalles de lo que escribí. Después de muchas solicitudes de documentación excesiva y solicitudes de capacitación de usuarios no técnicos sobre cómo administrar y alterar el código (sí, realmente), dejé de tratar de engañarla y me negué por completo. La analogía que solía explicar era simple:

• No soy contable
• No debería esperar entender cada transacción o publicación en nuestras cuentas
• Esto no significa que las cuentas estén equivocadas o no sean confiables, simplemente porque no las entiendo
• Esto es posible al confiar en la persona que los compiló

Al final de todo, esto es lo que me parece a mí: un gerente que tiene dificultades para confiar en sus empleados; o teme que se irán, y piensa que esta es una forma efectiva de mitigarlo.

La única solución a esto es sentarse y explicar por qué esto no tiene sentido. Es su trabajo comprender el código y hacer posible que alguien con un conjunto de habilidades similar al suyo lo entienda, no el de su gerente. Mostrarles este hilo puede ser una buena idea (o una muy, muy terrible, dependiendo de su personalidad).

Línea por línea, es ridículo. Lo que podría sugerir es ofrecer generar documentos a partir de comentarios y darle eso. Eso fue suficiente para varias subvenciones y auditorías del gobierno canadiense en las que he trabajado en el pasado.

No obtendrá línea por línea, pero obtendrá método por método, que aún debería ser más granular de lo que necesita.

Algunas soluciones existentes, dependiendo de su plataforma:

• C #: castillo de arena
• Java: javadoc
• "C ++, C, Java, Objective-C, Python, IDL (sabores Corba y Microsoft), Fortran, VHDL, PHP, C # y, en cierta medida, D". : doxygen

Sería mucho más rápido para él aprender a leer código que traducir todo el código de cualquier aplicación interesante al inglés. Además, lo intentamos con COBOL y no sirvió de nada. Si no está dispuesto a aprender, pero solo quiere hacer de su ignorancia el problema de otra persona, usted tiene un jefe seriamente puntiagudo.

Use su experiencia técnica para perseguir a su jefe.

1. Hágale saber que tomará tanto tiempo hacer esto como lo hizo para codificarlo en primer lugar (siéntase libre de hacerlo más largo).
2. Pregúntele qué tan actualizado debe estar este documento. Infórmale que todos los cambios de codificación ahora tomarán al menos el doble de tiempo.
3. Si usted u otra persona encuentra algún error, pregúntele si debe solucionarlo ahora o esperar hasta que haya terminado la codificación de psuedo. Recuérdele acerca de # 1 y # 2

Como todas las malas sugerencias de solución, es mejor identificar el problema. Tal vez su jefe está siendo golpeado con preguntas técnicas por la alta gerencia y se siente avergonzado porque no puede responder. Podría haber una sección particular de código que le preocupa más, por lo que podría limitar esta empresa masiva a esa área.

Al enviar una muestra, puede llegar a la conclusión de que si no comprende cómo funciona la codificación (¿Qué es un bucle y qué está haciendo con todos estos elementos?) No importa en qué idioma está. Es mejor fuera de entender la aplicación desde una perspectiva de usuario avanzado. Creo que es justo que le hagas saber que prefieres escribir código / pista real: estoy buscando otro trabajo.

¿Por qué?

Un comentario línea por línea no es razonable, pero esto es lo que preguntaría: ¿por qué quieres esto?

¿Es porque ...

• ¿Quieres una comprensión completa de lo que hace el software (no necesariamente cómo)?
• ¿Quieres estar seguro de que otro programador puede retomar el proyecto si me voy?
• quieres ver que estoy haciendo un trabajo real?

Puede haber un deseo razonable detrás de esta solicitud, y usted puede hacer feliz a su jefe al descubrirlo y satisfacer esa necesidad.

Actualizar

Basado en un Mikey'scomentario, tal vez dije esto un poco sin rodeos. No quiero decir que literalmente debas decir "¿por qué quieres esto?", Solo que debes descubrirlo . La redacción y el tono de voz hacen una gran diferencia. Específicamente, podrías decir algo como:

"He estado pensando en su solicitud de tener una explicación de cada línea de código. Es un poco inusual hacer las cosas de esa manera. Me preguntaba si tal vez hay algo que no le estoy comunicando bien sobre mi trabajo. ¿Qué es lo que realmente quieres entender sobre nuestro código, o sobre lo que estoy haciendo? ¿Qué estás tratando de lograr aquí? "

Por supuesto, es posible que tu jefe sea totalmente irracional. Pero es más probable que él no sepa cuán extravagante es esta solicitud y tenga algún objetivo racional en mente.

Si no, comienza a pulir tu currículum. :)

Suena como una buena oportunidad para probar la programación alfabetizada. Buscalo en Google. :)

Pero ... no es necesariamente una solicitud totalmente irrazonable. Parte de su trabajo (la parte más importante, imo) es comunicar sus algoritmos a otros desarrolladores y, si es necesario, a personas no técnicas. Los programadores genios solitarios que no pueden comunicarse son siempre problemáticos, creo.

Con ese fin, su código debe ser muy claro (es decir, ya sea realmente autodocumentado o bien documentado, y por "autodocumentado" me refiero a que las variables y funciones tienen un significado o responsabilidad y sus nombres lo reflejan claramente). Su jefe puede tener buenas razones para su solicitud. Tal vez (supongo que aquí) usted o su predecesor tienen una reputación de código impenetrable y frágil y este es el remedio de su jefe. Es un poco extremo, pero podría ser un ejercicio útil para usted. Supongo que él sabe que lleva tiempo escribir mejores documentos (y si no lo hace, debería ser educado; es como escribir un trabajo final: lleva más tiempo escribir que leer).

Incluso una traducción de línea por línea no transmitirá efectivamente el significado de cada línea de código. La comprensión de los programadores de una línea de código siempre está en el contexto de muchos factores. Métete en algo así como una pieza de código multiproceso y la traducción al inglés no tendrá más sentido que el código sin procesar. Piense en la funcionalidad que se extiende entre múltiples funciones / archivos. Algún código no tiene absolutamente ningún sentido sin explicar grandes cantidades de otro código. Intente explicar las diferentes partes involucradas en la inyección de dependencia "línea por línea" y verá lo que quiero decir. Casi cualquier cosa que vaya más allá del código de procedimiento de la función de Dios requerirá una gran cantidad de conocimientos de programación solo para comprender la traducción al inglés. Además, mire algo tan simple como una declaración de decisión if / else. No hay línea por línea, ya que la siguiente línea depende de los datos de tiempo de ejecución. La siguiente línea podría ser una de varias posibilidades.Para cuando haya explicado lo que hace su solicitud, habrá convertido su PM en un programador y ambos serán 5 años mayores.

Como solía enseñar programación, estaría muy feliz de intentarlo.

Rápidamente descubrirá que está obteniendo más de lo que esperaba, lo que me entristecerá porque me gusta explicar las cosas :-)

Cuando se refiere a su 'Jefe', ¿se trata de "un gerente intermedio a cargo de usted / su equipo"? o el propietario de su empresa? ¿Le pagan "por hora" o "con un salario"?

SI su jefe es un gerente de nivel medio que es responsable, HABLE CON SU JEFE, señale que para cumplir con los requisitos de su jefe, su productividad para la empresa se reducirá a 1/3 de lo que podría ser.

SI su jefe es "el tipo que firma los cheques", explíquele lo mismo, solo que más diplomáticamente. Su trabajo ha pasado de "Escribir el código" a "Escribir el código, escribir la explicación del código, explicar la explicación".

Un diagrama de flujo probablemente será de mayor beneficio para él. Esta es ciertamente una solicitud inusual y no dice mucho sobre él como gerente.

El hecho de que su jefe esté dispuesto a pasar un tiempo entendiendo el código que escribió, podría utilizarlo para su beneficio. Intenta presentarle a Pepino: http://cukes.info/

y haga que su jefe escriba la prueba BDD para usted en el futuro.

No debería molestarse en saber nada de eso. Dígale que en la implementación del desarrollo de software está sujeto a cambios. El diseño del evento está sujeto a cambios. Cuéntale sobre el ocultamiento de información, la encapsulación y la abstracción.
Él, como parte de su equipo, como cliente de su código, en un sentido más amplio, solo debería trabajar con una abstracción clara y de alto nivel de lo que hace su código. De la misma manera, cualquier capa de su código funciona con otra capa del código de otra persona. Saber algo más que eso solo lo ralentizará y corre el riesgo de que haga suposiciones basadas en el funcionamiento interno de su código. Esas suposiciones cesarán, cuando tenga que cambiar su código, lo que se convierte en un problema, si él construyó algún tipo de sistema o proceso basado en ellos.
Y también tener que hacer este tipo de trabajo reducirá su eficiencia. No solo tendrá que hacer cambios posteriores en dos lugares diferentes, sino que también tendrá un impacto negativo en la moral de su trabajo, lo que reducirá aún más su producción.

La belleza del inglés es que se ofende maravillosamente. Si usa esto para su ventaja, es posible que nunca tenga que tratar con este tipo de solicitud nuevamente. Tomaría un pequeño fragmento del código como muestra, pero uno muy abstracto y nada fácil de entender. Luego escribiría los comentarios en inglés técnico como si lo estuviera escribiendo para un capítulo en un libro de programación. Cuanto más largo y más complicado de seguir, mejor. Dígale cuántas horas le tomó documentar esta característica. Luego explique que es solo 1/10 del 1% (si puede, use cifras reales basadas en líneas de código, probablemente sean peores que esto) de la base de código real. Cuando se da cuenta de que no tiene idea de lo que dice la traducción al inglés y que tomará 20,000 horas hombre para hacer este nivel de documentación, retrocederá bastante rápido. Pero intente muy seriamente cumplir su tarea. No intentes esto si no puedes lograrlo y sospecha que estás jugando con él.

¡Esto parece un candidato para una tira especial de Dilbert de jefe de cabello puntiagudo con un tema festivo ! Su solicitud ciertamente no suena razonable a primera vista.

Dejando de lado el humor, trate de descubrir qué es lo que realmente necesita y por qué, luego infórmele sobre cuánto le costará en dólares u horas darle eso y déjelo decidir si quiere gastar tanto dinero en él.

En cuanto a usted, cuente las horas que le tomará cumplir con su solicitud aparentemente extraña y luego determine si no sería mejor invertir una fracción de esa cantidad de tiempo en encontrar un nuevo trabajo para un empleador dispuesto a tratarlo como profesional!

Tráelo a tu oficina y dale un recorrido por tu código.

A medio camino se dará cuenta de que hizo una demanda absurda, y se irá y nunca más te molestará.

Si no cedes a sus demandas para ayudarlo a tratar de entender tu código, encontrará formas diferentes pero igualmente absurdas de molestarte.

Este es un caso donde el apaciguamiento funciona mejor que la abrasión.

Sería muy bueno si tuviéramos un traductor "Language X to English" que haga esto. Entonces uno podría sonreír y decir, no hay problema, jefe, lo tendrá en un minuto. Y luego viene un correo con algunos megabytes de texto que dice:

• Sea un nuevo conjunto de enteros con 20 elementos.
• Deje x ser una variable para almacenar enteros.
• Establezca x en 0
• Mientras x es menor que 20, haga lo que se prescribe en las siguientes 2 líneas
• establece el elemento de matriz de a con el índice x al resultado de llamar a nThPrime con el argumento x + 1
• aumentar x en 1
• ....

Otra opción sería sugerir programación en Shakespeare en adelante.

Mi jefe quiere una explicación narrada en línea línea por línea de nuestro código

Difícil.

Como no es programador, no puede seguir el código, por lo que quiere que todo esté traducido al inglés.

Si no es un programador, no debería estar leyendo el código. En absoluto.

Proporcione documentación de alto nivel en su lugar.

Esta no es una solicitud razonable, ¿verdad?

No.

Como programador, realmente tienes "dos" trabajos.

El primero es crear buenos programas. El segundo es "venderlos" a clientes dentro y fuera de la empresa.

La solicitud de su jefe "lastima" su primer trabajo. Lleva más tiempo documentar sus programas. Por otro lado, en realidad te está haciendo trabajar más duro en tu "segundo" trabajo.

Su jefe le pide que documente su programa en inglés para SU beneficio, y presumiblemente para beneficio de las personas con las que tiene que tratar, dentro y fuera de la empresa. Si lo ayudas a hacer su trabajo, debería ser beneficioso para ti a largo plazo, cuando le pides más hardware, personal o dinero para los aumentos. Después de todo, él te pidió que hicieras más trabajo.

Creo que BDD encajaría bien con este problema, aunque parece que su proyecto está casi terminado, por lo que es un poco difícil implementarlo ahora, por lo que es más como una referencia futura.

Con BDD, los casos de uso se describen como documentos legibles por humanos que luego se traducen en pruebas funcionales automatizadas.

Probablemente, esta solicitud es un buen momento para aprender cosas como ANTLR . Tome ANTLR, tome la gramática de su idioma, analice todo el código que tiene, recorra su AST generando descripciones basadas en plantillas para cada nodo, así i++se describe como increase i by 1 using postfix increment operator. Eso debería ser muy divertido. Su jefe también puede querer que esta herramienta se incluya en el script de compilación, por lo que cada vez que realice algún cambio, recibirá un correo electrónico de ~ 20 MB que describe lo que hace la nueva versión.

PD Solo bromeo, es un idiota.

Aunque estoy de acuerdo en que esta es una solicitud irrazonable, su jefe puede apreciar algo como la salida de Docco , que separa su código y los comentarios línea por línea o cláusula por cláusula en la salida HTML de dos columnas, con el código en uno lado y prosa por el otro. Debe escribir los comentarios usted mismo, por supuesto, pero la presentación es bastante buena en mi humilde opinión, incluso para lectores no técnicos. Vea, por ejemplo, una sección comentada línea por línea del código anotado para Underscore.js . También hay versiones de script Python y shell.

Es posible que su jefe simplemente esté desinformado e intimidado, pero en realidad sea una persona razonable. Si es así, razonar con él / ella podría funcionar: una conversación informal en la que promete proporcionar "lo que realmente quiere", es decir; Una guía en prosa sobre lo que está haciendo el programa.

Si se trata de "mi camino o la autopista", mejor revise su gas ahora.

¿Podría escribir algunas pruebas de aceptación utilizando un marco de diseño basado en el comportamiento como el pepino ? Eso no explicará el código; explicará lo que hace, y en lenguaje natural. También tiene la ventaja de ser ejecutable, por lo que siempre puede estar seguro de que la documentación está actualizada, porque si no lo está, el corredor de prueba será rojo.

Mira el video de introducción. Quizás sea una buena diversión mientras encuentras un nuevo jefe ... ;-)

Es casi seguro que su gerente está angustiado por el hecho de que no comprende lo que hace la gente que está administrando, y no tiene los antecedentes para comprender los resultados que producen.

Dudo que haya pensado esta solución a fondo, y probablemente le pareció razonable a primera vista. Pero eso se debe principalmente a que no entiende qué es realmente el código de programación.

Cualquier programador comprende lo absurdo de esta solicitud, pero lo hacemos porque intuitivamente sabemos que una vez que superas el lenguaje, todo lo que se revela es el algoritmo, que es igualmente críptico.

// Set s to the first address in the server list
server_info *s = cmd->servers;
// Loop until s is NULL
while (s) {
    // call the server's init function passing our current ID and address
    s->init(proc->id,*addr);
    // call log::info with our custom message
    log::info("Starting server %s",s->name);
    // Set s to the value returned by the server's next() function
    s=s->next();
} // end of loop

El problema aquí es que, si bien los comentarios explican lo que hace cada línea, aún no tienes idea de lo que realmente hace el código a menos que entiendas cuáles son todas las implicaciones. Es obvio si eres un programador y has visto este patrón antes; pero muéstrale esto a alguien que solo entienda las ventas, y estará tan confundido después de leer los comentarios como antes.

En realidad, podría ahorrar tiempo al enseñarle a su jefe una programación básica. Si quiere leer tu código, dale las herramientas para poder hacerlo. La mayoría de los idiomas tienen una sintaxis bastante compacta, y aprender la estructura solo lleva una o dos horas. Es casi seguro que se dará por vencido después de unos días, pero al menos sabrá lo que está transmitiendo y, lo que es más importante, por qué no quiere leer su código.

En mi humilde opinión ... si él es responsable de hacer la tarea, debe saber cómo funciona ... :)