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

155

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.

Billy Moon
fuente
Bloqueado por razones históricas, consulte "Bloquear las preguntas más votadas que están cerradas" para obtener más detalles.
Yannis

Respuestas:

160

¡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.

torre
fuente
Interesante: vaya a leer las conferencias de Richard Feynmans sobre física. Encontrará que gran parte de él es un argumento cuidadosamente redactado, en inglés (si X entonces Y debe ser cierto, y por lo tanto Z ... etc.). Pequeñas matematicas. Lo que quiero decir es que puedes explicar las cosas en inglés. Si DEBERÍAS ser otro asunto.
rapid_now
1
@quickly_now: léelos hace mucho tiempo durante la universidad. No es una mala lectura. Estoy de acuerdo, puedes explicarlo, puedes explicarlo en cualquier idioma cuando la persona a la que le estás explicando ya comprende la "abstracción" detrás de esto (código, ecuación matemática y significado ...) // Si no lo hace t: tendrás problemas para explicarlo en cualquier idioma.
Torre
44
@Rook: buen punto. Explicar la mecánica cuántica a una tribu primitiva cuyo vocabulario se limita a la dirección en la que se movía el alce sería un poco difícil.
rapid_now
Podría obtener la 'intención' de su gerente a veces de microgestión. Pero, si el código era muy claro en sí mismo, entonces puede leerlo como un texto en inglés.
Arvind Chinniah
150

¿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.

xtian
fuente
15
Por eso especifiqué: "Un administrador que no sea de programación no debería necesitar más que eso".
Malfist
35
@Loren Pechtel: Me gustaría ubicarme allí y ver a este tipo leer páginas de "Crear una variable entera llamada X. Establecerla en 0. Crear una variable entera llamada Y. Establecerla en 0. Crear una variable entera llamada Z . Establezca en 0. Cree una variable entera llamada posición X. Establezca en 0. Cree una variable entera llamada posición Y. Establezca en 0. Cree una variable entera llamada posición Z. Establezca en 0. Cree una variable entera llamada Rotación X. Ajústelo a 0. Cree una variable entera llamada Rotación Y. Ajústelo a 0. Cree una variable entera llamada Rotación Z. Ajústelo a 0. "...
FrustratedWithFormsDesigner
99
@Frustated ¡Es mucho más fácil con el resaltado de sintaxis! " [p32767, l21, c8] Aumentar pXen el tamaño de un Integer. Aumentar Sumen el valor señalado por pX. Aumentar ien 1. Si ies menor que 3, vaya a la página 32768, línea 17, columna 42. De lo contrario, vaya a la página 32767 , línea 21, columna 8. "
Mateen Ulhaq
99
@muntoo, necesita alinear todas esas funciones para no tener que ir y venir de una página a otra. De lo contrario, uno podría tener muchos problemas para volver a subir a la pila.
Kibbee
15
@ Frustrado: Entonces, ¿qué voz te estás imaginando? No puedo decidir entre Sean Connery y Morgan Freeman.
Beta
113

¿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?

psr
fuente
21
+1 para diagnosticar microgestión. En mis propias palabras: ¡ saca el f___ de allí!
tdammers
@tdammers: afortunadamente, este es el tipo de cosas que puedo decirle a mi jefe. ¡Es un buen tipo además de ser un jefe!
heltonbiker
55
Un administrador que necesita comprender cada línea del código se llama programador.
James P.
91

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?

reinierpost
fuente
57
Asegúrese de que después de haber pasado dos horas explicando diez líneas, él comprende que quedan 50,000 (o lo que sea) líneas de código que quedan por explicar.
HLGEM
66
En realidad, es una forma muy sensata de seguimiento. Hazle ver la ignorancia de sus caminos.
Kibbee
44
@reinierpost: tu método es puro genio.
heltonbiker
55
Si vas a hacer esto, primero dile al jefe por qué es una mala idea en general y LUEGO demuéstralo. Si no lo hace, puede parecer que le está haciendo un "truco" y lo pone a la defensiva.
nerdytenor
55
¡Nunca le digas a la gente que sus ideas son malas! Sin embargo, puede discutir qué se necesitaría para hacerlos realidad, y tal vez incluso dar algunas ideas para tomar atajos. Si esto los lleva a concluir que la idea no era viable, o hace que la idea inicial se transforme en algo completamente diferente, y en algún momento lo noten, se encogerán de hombros y dirán: así es la vida.
reinierpost
43

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.

Pablo Santa Cruz
fuente
13
Incluso con una traducción al inglés , un no programador puede creer:/* and this line is transferring deposits to the correct account */ deposits.TransferAll(acctInfo);
Extracto del
15
Si el jefe "teme que va a hacer que su código haga algo que no aprueba o sabe", esto no hará nada para aliviar sus temores. La misma persona está proporcionando la traducción que escribió el código. ¿Qué les impide mentir sobre lo que hace? Algo más está sucediendo aquí.
mmc
44
COBOL estaba destinado a ser leído en inglés.
oosterwal
1
Quizás está tratando de descubrir qué hace el código para ver si está de acuerdo con el razonamiento y quizás obtener mejores ideas. En cualquier caso, no es su trabajo hacerlo, al menos no de esa manera ...
heltonbiker
32

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).

John N
fuente
¿Cómo tomó su gerente su explicación?
Jeff Martin
1
Exactamente tan bien como podrías esperar. ;) Sin embargo, el punto se hizo y las solicitudes se detuvieron. No sé si eso fue porque la convencí de la validez de mi argumento o si decidió que no valía la pena y se dio por vencida.
John N
25

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
Steven Evers
fuente
Como hay Pas2Dox, agregue Delphi a la lista de doxygen ;-)
Fabricio Araujo
Ir al enlace de Sandcastle. Mira impresionado. Haga clic en la pestaña "Documentación". Consulte el mensaje "Este proyecto aún no tiene documentación". Parece menos que impresionado.
Kaz Dragon
16

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.

Kevin Cline
fuente
3
Creo que el inglés debería ser el idioma. El jefe debe solicitar que todo el software se escriba en un DSL (lenguaje específico del dominio), luego puede hacer cambios en la forma en que funciona el sistema.
David d C e Freitas
Creo que la mención de Cobol lo resume. Cualquiera que haya impreso un simple hola mundo sabe cuán ridículamente prolijo es este lenguaje. Fue un buen movimiento hacia algo inteligible pero demasiado formal.
James P.
15

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.

revs JeffO
fuente
77
debemos tener cuidado al caracterizar a alguien como "un idiota". Si bien es personalmente satisfactorio para nosotros como programadores hacer esto, no creo que sea profesional, y cualquier solicitud de cualquier gerente, por extraño que sea, debe tratarse en función de sus méritos.
funkymushroom
66
@funkymushroom: Los méritos de esta solicitud son que es un idiota.
DeadMG
3
@funkymushroom - Creo que se nos puede permitir un poco de ligereza en este sitio. Después de todo, vas por hongos funky.
JeffO
2
@ Jeff: Punto bien tomado. De ninguna manera soy un palo en el barro. Sin embargo, hay dos tipos de "idiotas". El "Idiota Malicioso" y el "Idiota Ignorante" y yo hemos trabajado con ambos. El primero debe ser ignorado, es peligroso para nuestras carreras y el segundo puede ser un buen aliado, por lo que debemos enseñarle.
funkymushroom
@funkymushroom: de acuerdo, así que lo saqué.
JeffO
12

¿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. :)

Nathan Long
fuente
-1 para esta respuesta: si desea conservar su trabajo (o al menos dejarlo voluntariamente), no debe preguntarle a ese jefe 'por qué'? Esto es algo que debe ser refinado, como lo han sugerido otros.
Vector
3
No estoy de acuerdo con el comentario de Mikey. Seguir ciegamente las órdenes es una tontería. Preguntando "¿por qué?" En cada solicitud me ahorré innumerables horas de trabajo innecesario y ahorré a mi empresa mucho dinero en el proceso. Se llama consulta, y aquellos que no temen a sus jefes lo hacen de manera liberal y con gran efecto. Cuando las personas que trabajan para mí sugieren algo, también les pregunto "¿por qué?" también. En ambos casos, busca justificación, y es perfectamente aceptable hacerlo.
Soviut
10

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).

revs JohnL4
fuente
He echado un vistazo a la página de Wikipedia. Me recuerda el "estructurado <insertar lenguaje humano aquí>" que vi durante los estudios. Utiliza el lenguaje humano para representar la estructura de programación línea por línea con expresiones if blah then add 1 to xcomo una alternativa a nassi-schneiderman o diagramas de flujo. ¿Es esto lo que se entiende por programación alfabetizada?
James P.
Usted es el único en esta página, que menciona la programación ilustrada de Knuth - me hace pensar bajo qué roca el resto de carteles vivió durante cuarenta años ...
CJI
@ James: compre una copia de "Tex - the program" de Knuth y léalo. Esta es la programación alfabetizada.
cji
10

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.

Morgan Herlocker
fuente
10

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 :-)

Mike Dunlavey
fuente
3
Creo que esta es la mejor respuesta aquí. No entiendo toda la renuencia a intentarlo, ¡quiero decir que te pagarán por sentarte allí y explicar tu código! Demonios, a menos que su código sea una mierda, probablemente lo disfrutará, y no importa cuán bueno sea, probablemente encontrará algunos errores y lugares para mejorar.
Bill K
1
Tuve un maestro que me explicó cosas mientras escribía el código que se muestra a través de un proyector. Tal vez esto podría hacerse un poco como una lección de manejo. Si no puede leer todo el código, al menos puede dar una mejor idea de lo que se está haciendo y cómo.
James P.
1
Estoy tratando de entrar en el negocio de la enseñanza y di una respuesta similar. Estoy con @Bill, estoy muy decepcionado de que la gente adopte una postura tan solitaria. ¿Estamos jodidos por creer que vale la pena pasar el tiempo explicando incluso una pequeña parte del código?
Rei Miyasaka
1
@Rei: Las actitudes, malas o buenas, tienden a apoderarse de grandes subconjuntos de personas similares. He tenido una amplia experiencia (ingeniero, estudiante graduado, profesor, consultor, empleado a largo plazo), así que me gusta pensar que eso da una perspectiva. Además, mis actitudes han cambiado con los años.
Mike Dunlavey
10

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".

ingrese la descripción de la imagen aquí

Cos Callis
fuente
¿Por qué no hacerlo y tomar el dinero? ¿Estás tan seguro de que a tu único valor le gusta producir código como un mono?
Bill K
9

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.

James
fuente
18
En realidad, me dice mucho sobre esta persona ...
Marjan Venema
55
Eso es lo que "no dice mucho sobre" significa en este contexto: dice mucho, de hecho, pero simplemente no indica mucho bien sobre el individuo.
Joseph Weissman
8

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.

destello de luna
fuente
He estado tratando de usar Pepino en mi tienda por un tiempo ... desafortunadamente (¡o quizás afortunadamente!) A mi jefe no le importa lo que sucede detrás de escena, siempre y cuando funcione. Hacer que entendiera el beneficio de escribir pruebas primero fue una batalla cuesta arriba.
Jason Lewis
6

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.

back2dos
fuente
6

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.

HLGEM
fuente
6

¡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!

John Tobler
fuente
1
Un análisis de costo-beneficio debería hacer el trabajo. Tal vez el gerente tenga algunos beneficios adicionales que aportar. Si no vale la pena, es difícil hacer cumplir y defender a la alta gerencia.
mbx
6

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.

Rei Miyasaka
fuente
+1 - Estaba pensando en la misma línea - aceptarlo en la solicitud - probablemente se aburrirá y / o te matará de miedo en poco tiempo ...
Vector
+1 Me gusta eso - "funciona mejor que la abrasión".
Mike Dunlavey
6

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.

Ingo
fuente
Iba a hacer la misma sugerencia. El jefe no quiere una descripción conceptual, la quiere línea por línea, por lo que debería ser posible producir algo en un día o así que se cree una documentación completamente inútil pero superficialmente correcta. No importaría si se tratara de un nido de ratas de if-elses en perl que se confundía fácilmente con los casos de esquina, solo identificaría declaraciones de variables, modificaciones a variables, llamadas a métodos, etc. (recuerde que es línea por línea, no manera asimila el código).
PhilDin
Sí, este jefe es simplemente ignorante. No sabe qué es "abstracción", no sabe que el inglés no es bueno para expresar programas de computadora, no puede imaginar que realmente no quiere conocer todos esos detalles, por eso le paga a un programador. Por lo tanto, merece una lección como esta.
Ingo
5

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.

Carreras de ligereza en órbita
fuente
4

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.

Tom Au
fuente
3
Documentando línea por línea! = Vendiendo el proyecto. Ya debería haber un documento que proporcione esta información, se llama requisitos. Estoy de acuerdo con la descripción de sus 2 trabajos, pero documentar a ese nivel no será beneficioso para vender el proyecto / sistema / aplicación. Existe un nivel apropiado de documentación para presentar su trabajo, y este no es el caso.
cdkMoose
Apuesto a que la persona que escribe los cheques en esta compañía no estaría contenta de que este gerente desperdiciara tantos recursos de la compañía.
JeffO
@ Jeff O: Podría ser. O podría ser que TODA la compañía es así, hasta la cima.
Tom Au
4

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.

Inoryy
fuente
Esta puede ser la sugerencia más constructiva hasta ahora. El desarrollo basado en el comportamiento está diseñado para satisfacer exactamente esta necesidad: ayudar a los programadores y sus gerentes / clientes a ponerse de acuerdo sobre lo que hace el software. Escribir las descripciones ayuda a planificar el código, y ejecutar las pruebas demuestra que todavía son descripciones precisas.
Nathan Long
4

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.

Peter Mortensen
fuente
3

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.

btown
fuente
Esta es una de las respuestas más útiles que he visto para la pregunta. Realmente intenté usar docco, pero descubrí que estaba teniendo problemas con algunos de mis comentarios existentes, y lo hice incorrectamente. Por lo tanto, fui con JSDoc en su lugar, y seguí las pautas de Google para generar la documentación. No tan bonito, pero muy completo, y también un formato estándar. El problema con docco para mí es que necesitas estructurar tu código para que se adapte a los comentarios, o no tiene sentido. Gracias por la sugerencia.
Billy Moon
3

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.

ddyer
fuente
3

¿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 ... ;-)

Peter Mounce
fuente
2

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.

tylerl
fuente
1

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

John K.
fuente
2
¿Te refieres al gerente o al programador?
Nathan Long
¿Cuántas empresas pueden permitirse que cada gerente no técnico use tanto tiempo de desarrollador?
JeffO