¿Cómo puedo pedirle a mi jefe (de manera educada) que comente su código?

Estás en el 'final profundo' y, en mi opinión, esa es la mejor manera de aprender. No porque estés viendo cosas de las que no tienes ni idea, sino porque te obliga a tener más recursos y descubrir qué componentes desempeñan qué papel en un sistema en el que eres nuevo.

No ayuda que su jefe esté demasiado ocupado para manejar a alguien que es inquisitivo (y está totalmente dentro de sus derechos para ser inquisitivo; está dispuesto a aprender, lo que es bueno). Pero, desafortunadamente, pedirle a su senior que cambie su estilo y enfoque por el bien de su aprendizaje puede que no le caiga muy bien, especialmente porque está tratando con alguien que dice que está ocupado.

Estar sentado frente a miles de líneas de código con las que no está familiarizado es la norma. No siempre se puede explicar en blanco y negro con comentarios. Sin embargo, por el simple hecho de aprender mientras eres nuevo en eso, si sientes que definitivamente tienes que pedirle comentarios, tal vez explique por qué. Explique que se debe al hecho de que no quiere molestarlo con preguntas, ya que a menudo está ocupado. Esto no solo se verá mucho menos como si le estuvieras diciendo que haga algo, sino que también abre el piso a las discusiones sobre cómo podría, en cambio, preferir dejar de lado las preguntas.

Primero, rastrear miles de líneas de código desconocido y sentirse perdido es cómo cada proyecto de software es, en todas partes, desde el principio de los tiempos.

La mayor diferencia entre usted y un programador experimentado es que no está acostumbrado.

Algunos puntos a tener en cuenta:

1. Con suficiente esfuerzo, cada parte del código es comprensible. Muchas personas se sienten frustradas si no pueden resolver algo en unos pocos minutos. Sé más paciente que eso.

2. Un buen jefe es lo más abierto posible a las interrupciones y preguntas. Un buen empleado hace todo lo posible para minimizar las interrupciones y las preguntas. Sé consciente de eso.

3. Las interrupciones son más costosas que las preguntas. Puede hacer un mejor uso de su tiempo y del tiempo de su jefe al consolidar sus discusiones y al no terminar nunca una conversación sintiéndose confundida.

4. Tu jefe es mejor programador que tú. (Probablemente). Eso no quiere decir que no pueda ser más fuerte en algunas áreas, pero en general su experiencia es mayor. Hasta que tenga mucha experiencia, asegúrese de aprender de su experiencia tanto como pueda.

5. Si está seguro de que más comentarios ayudarían significativamente al código, pregúntele a su jefe. "Es difícil para mí entender lo que está pasando en algunos lugares. Cuando resuelvo las cosas, ¿te importa si agrego comentarios?" Tal vez él odia los comentarios. Tal vez él lo ame. Tal vez sea indiferente.

Al final, sin embargo, es posible que dentro de un par de meses recuerdes haber preguntado esto y pensar: "¿Eh, me pregunto con qué tuve un problema? Esto no es tan malo. Hm, bueno, no importa ".

Si su jefe no tiene tiempo para responder todas sus preguntas, ¿por qué cree que tendrá tiempo para comentar su código heredado? Y, además, ¿qué te hace pensar que sus comentarios realmente describirían los fragmentos que no entiendes por ahora? Según mi experiencia, tratar de cambiar el estilo de programación de sus jefes simplemente pidiéndole que no funcione, sea cortés o no.

Lo mejor que puede hacer en una situación así: comente las partes del código que necesita comprender para hacer su trabajo usted mismo : una vez que haya comprendido esas partes, por supuesto, y después de obtener Un compromiso de tu jefe de que esto estará bien. Si usted o su jefe temen que pueda romper algo agregando comentarios, agréguelos en una sucursal separada y pregúntele a su jefe si se tomará el tiempo de revisar sus comentarios antes de que se unan al tronco. Como su jefe solo tiene un presupuesto de tiempo limitado, intente averiguar qué parte determinada hace primero usted mismo invirtiendo una cantidad de tiempo razonable. Si realmente te quedas estancado, escribe tu pregunta en una lista y pregúntale a tu jefe, por ejemplo, una vez al día en lugar de molestarlo durante 30 minutos. Según mi experiencia, este enfoque funciona con la mayoría de las personas, incluso si están muy ocupadas, siempre que estén dispuestas a ayudarlo, lo que seguramente es el caso en su situación.

De esta manera, está seguro de que recibe los comentarios que necesita, y su jefe verá dónde necesita información adicional, y si está en lo cierto. Y siempre que se limite a comentar solo las cosas que no son obvias, existe la posibilidad de que sus comentarios aumenten la calidad general del código base, lo que no solo le traerá beneficios no solo a usted, sino también a todos los demás. tiene que lidiar con el código, incluido su jefe.

En primer lugar, deje que este sea un ejemplo para que comente correctamente su código, ¡saltamontes!

Entonces, tengo que hacer esto todo el tiempo. He revisado mi copia local, la reviso y la comento yo misma. (Puedo sacarlos a todos nuevamente si voy a revisarlo nuevamente, o dejarlos adentro, si a nadie le importa). Entonces, cuando ya no puedo ver más, puedo preguntar a alguien, aquí, creo que sí. Esto (lo que comenté), ¿verdad? Es posible que hayas hecho el comentario real, pero está hecho y ese es el punto.

Esto es más que una simple solicitud personal. Estás tratando de cambiar hábitos / cultura, y eso no es fácil. Ciertamente no es algo que se pueda lograr mediante una conversación en el pasillo o un correo electrónico. Tomará un poco de esfuerzo por tu parte.

  

Sé el cambio que deseas ver en el mundo.

La cita puede ser falsamente atribuida a Mahatma Gandhi, pero es un consejo aplicable. Cuando intente descifrar el código base, escriba los comentarios que le gustaría haber visto, lo mejor que pueda y coméntelos, después de que su jefe los haya revisado. Ventajas:

• Estás siendo proactivo, en lugar de molesto.
• Estás dando un buen ejemplo. En el mejor de los casos, su jefe / equipo verá los beneficios y hará lo mismo.
• Es probable que algunos de los comentarios digan /* Mystery parameter 3 */ o /* 2015-02-09 AidanQuinn: Is this code ever called? */ ; esas son oportunidades para que sus colegas documenten el código correctamente o corrijan errores latentes.
• Si, durante la revisión previa a la confirmación, se descubre que un comentario que usted escribió no es exacto, sus colegas ahora saben que el código no estaba claro.

Abstenerse de cualquier reescritura o refactorización al hacer esto, y la introducción de comentarios debería estar casi libre de riesgos. Si reescribe algo, mantenga esos cambios como confirmaciones separadas.

(Sin embargo, antes de embarcarse en este proyecto, asegúrese de que sus expectativas de comentarios sean razonables. Si su idea de un código bien comentado está fuera de la norma ( Ejemplo 1 , Ejemplo 2 ), entonces solo estará haciendo el ridículo de ti mismo.)

No pediría comentarios adicionales, pero aquí hay algunas ideas para ti:

1. Programe una reunión con su jefe y pídale que revise el código a un nivel alto. Esto debería empezar. Espero de unas pocas horas a medio día para que pueda ponerse al día. Esto debe incluir el diseño general, los patrones utilizados, etc.
2. Cree un proyecto de pruebas y comience a escribir pruebas unitarias con el código, esto lo ayudará a entenderlo sin que esto afecte su impacto. ¡También puedes encontrar algunos errores también!
3. Depure el código según sea necesario para comprender ciertas áreas.
4. Retire una mejora o error de la acumulación y trabaje en ella.

Los comentarios están bien, pero si el código está escrito de manera directa, debería ser comprensible después de unos días.

Además, no espere entenderlo todo, es mejor centrarse primero en las áreas clave y luego ampliar el conocimiento de la base del código según sea necesario.

He estado en una situación muy similar a la tuya hace aproximadamente un año. Comencé a trabajar con poca experiencia en programación (aunque, para empezar, sabía un poco de OO y algunos otros idiomas) y la única persona que me enseñaba tenía muy poco tiempo. Siempre me ayudó, pero sentí que no me gustaría hacer todas las preguntas que tenía.

Otros ya han sugerido cosas extremadamente útiles aquí (por ejemplo, pruebas de unidad de escritura, pero desde mi propia experiencia, eso es algo que habría ido un poco "demasiado lejos" para mí desde el principio, o comentar partes del código usted mismo, pero eso puede ser difícil dependiendo del primer punto / pregunta que le haré en un minuto). Los siguientes puntos resumen lo que hice y lo que me ayudó, pero depende mucho de dónde se encuentran exactamente sus problemas.

También, estoy de acuerdo con @AK_ quien dijo que realmente no necesitas comentarios en C #. Puede que no sea 100% correcto (creo que hay áreas en las que los comentarios definitivamente ayudan, por ejemplo, el código de reflexión), pero en esencia lo es. Si realmente escribe 'código limpio' con métodos y variables bien nombrados, y tiene muchos 'fragmentos' de código, serán casi totalmente innecesarios. Cada vez que sentí la necesidad de comentarios al leer el código hasta el momento, luego de entender lo que hizo, me sentí muy descontento con la forma en que se hizo y pensé que podría haber sido mucho más claro en primer lugar por una buena refactorización. Editar: Estoy hablando específicamente de C # comentarios aquí, no de documentación (ya sea documentación separada o comentarios XML), ya que creo que la documentación siempre es importante.

• Identifique cuáles son exactamente sus problemas y si puede clasificarlos. Es decir, ¿sigue teniendo problemas con el lenguaje en sí o no comprende una sintaxis específica (por ejemplo, expresiones lambda y LINQ en general, o Reflexión)? Si no entiende las líneas de código, no entenderá lo que hace todo el método / bloque, por lo que comentarlo usted mismo será difícil. Más bien, obtenga un buen libro ('C # en pocas palabras' fue para mí, pero escuché que 'C # en profundidad' también es espectacular) y lea sobre las cosas que encuentra. Clasificar estos problemas de antemano hace que esto sea más fácil, ya que puede llenar 'vacíos más grandes' a la vez, o incluso preguntar a su jefe, ya que ya no son muchas preguntas, sino más bien explicar un solo tema o las construcciones más utilizadas para que puede obtener un gran 'impulso' en esta área rápidamente.

• Paralelamente a lo anterior, intenté familiarizarme con la "codificación limpia" y las mejores prácticas generales (no específicas del idioma). El efecto de esto puede no ser inmediato, pero se pagará tarde o temprano, ya sea cuando tenga que extender las cosas existentes o se pregunte por qué alguien creó tantos métodos pequeños en lugar de uno donde todo está contenido ;-)

• Comprende los patrones de diseño comunes. Es posible que aparezcan aquí y allá en el código que está leyendo, y si los reconoce, inmediatamente le dará un momento de a-ha. Incluso si entiendes lo que hace el código que ves allí, puede que te preguntes por qué se hace de esta manera, y descubrir esto por ti mismo a menudo no es tan fácil.

Por favor, no tome el texto anterior como yo haciendo suposiciones sobre su "habilidad", a menudo, accidentalmente, cambio entre hablar de mis experiencias y hablar "con usted". Se entiende principalmente como lo que encontré y lo que hice . Como han dicho otros, esta puede ser una experiencia muy buena y es bastante estándar en el trabajo leer un código que no es el tuyo y del que no sabes mucho de antemano. Pero puede ser realmente satisfactorio comprender finalmente lo que está sucediendo allí y reconocerse a sí mismo mejorando en esta 'habilidad' en particular. Aproveche esto como una oportunidad para aprender mucho mucho en muy poco tiempo, ¡buena suerte! :)

Probablemente no vas a lograr que cambie su estilo.

Lo que puedes hacer es hacer muchas preguntas y escribir las respuestas.

Heredé una base de código enorme en mi último trabajo, poca documentación y pocos comentarios. Por lo tanto, intentaría durante una media hora el mismo problema; luego, si todavía no pudiera resolverlo, preguntaría a alguien que lo haya escrito o que sepa cómo usarlo. Luego documentaría todas las cosas que me dijo. La mayoría fue en nuestra documentación, algunos fueron en el código como comentarios. Después de un año, prácticamente había escrito una gran parte de nuestra documentación y sabía mucho sobre el código base.

¡Buena suerte!

Estaba teniendo el mismo problema. Im estudiante de phyzist y tengo buena experiencia en programación. Estaba programando en muchos idiomas, pero nada para aplicaciones premium.

Solicité un trabajo para desarrollador web y al instante me pusieron al final de la programación web. Cuando el jefe me mostró el api base para la aplicación REST del nodo, estaba pensando en tirar. Nunca he visto funciones con devolución de llamada y sintaxis tan extraña. Y le pregunto a mi jefe si tengo un problema si no entiendo nada en el código. Él no está triste, está triste porque tengo 1 mes para averiguarlo y, mientras tanto, haré un CMS para probarme con otro frontender.

Bueno, fui 1 línea de código en ese momento y busqué en Google todo lo que no sabía. Así que pasé una semana y estaba lo suficientemente familiarizado con el código para poder colaborar con el director. Mi código al principio era una mierda, pero ¡véanme 3 meses después de eso! ¡Estoy codificando mejor y más rápido que nuestro arquitecto de software!

Sugiero que nunca dejes de aprender! Mi moto - > Sigue aprendiendo y mantén la calma :) No dependas de que el jefe sea independiente y pregúntale directamente, pero solo los problemas más difíciles. Porque serás feliz después de que lo hayas resuelto por tu propio jefe. Y recuerde que cuando deje de aprender que está mal, aprenda cada día cómo ser un buen programador.

Si aprende del jefe, nunca irá mejor que él. Establezca su propio estándar, aprenda la escritura a ciegas, el complemento VIM o VIM para su IDE, Linux wmii, por lo que algún día iría más allá del jefe y sería mejor que él!

Como ingeniero de software de 20 años de antigüedad, que trabaja principalmente en temas relacionados con la seguridad (SF-PD), debo decir que es posible que su jefe no sea la persona que desea que sea su ejemplo. La falta de comentarios es un signo de un programador aficionado autodidacta que nunca aprendió a hacer el trabajo correctamente, o de un ingeniero sin experiencia. O tal vez un ingeniero que simplemente no tiene tiempo: ¡los plazos y la conveniencia pueden hacer cosas horribles a su código! Sin embargo, es definitivamente un antipatrón para todos los ingenieros de software competentes.

Tu jefe puede ser un muy buen programador, pero parece que no es un buen ingeniero de software. Un ingeniero utiliza la experiencia colectiva del grupo para evitar las dificultades que otras personas ya han atrapado. Los comentarios efectivos forman parte de la experiencia grupal colectiva de software, de la misma manera que el análisis de estrés forma parte de la experiencia grupal colectiva de ingeniería mecánica. Sin embargo, lo que se considera un comentario efectivo es más fluido y definitivamente es algo que se obtiene de la experiencia.

Lo más básico es que los comentarios no deben decir lo que hace una línea de código. Hay ocasiones en que los comentarios para decir lo que hace una función también son superfluos (especialmente en C #). Hacer comentarios excesivos puede ser tan ineficaz (y un indicador de falta de experiencia) porque no puedes encontrar las cosas importantes en la escoria. Como novato, es posible que aún estés trabajando para averiguar el "qué" del código, y para eso solo necesitas leer y comprender lo que ha hecho.

Sin embargo, lo importante para los comentarios es que dicen POR QUÉ que una línea de código o una función hace lo que hace, donde esto podría no ser obvio. ¿Necesita configurar el módulo X antes del módulo Y? ¿Es importante verificar un código de retorno para ver si un archivo ya estaba abierto, o estamos ignorando conscientemente el código de retorno porque este ha sido verificado en otro lugar? El "por qué" del código será relevante para todos, independientemente de la experiencia, y también lo será para él dentro de 6 meses, cuando se le olvide la buena razón para hacer algo de una manera particular. Comentar no es solo para otras personas, sino también para ayudarlo en el futuro.

Si desea evitar molestar a su jefe, haga preguntas inteligentes. Concéntrese en preguntar sobre el "por qué" e intente resolver el "qué" usted mismo (a menos que realmente sea oscuro). A ningún buen jefe le importará que se le hagan preguntas si no son el tipo de cosas que podría haber encontrado en R-ing TFM. Y a ningún buen ingeniero le importará que se le pida que haga algo que hará la vida de otro ingeniero mucho más fácil, a un bajo costo para ellos. (¡No le pida que rellene los comentarios de la base de código completa!)

He estado en una situación similar, diría

1. Es posible que tu jefe quiera que aprendas de forma sucia (al recorrer el código del que no tienes idea) por una razón. Esta es la forma en que aprendemos más en un mes de trabajo que un año en la universidad, como se menciona en otras respuestas.

2. Esta es "la norma" como se menciona en otras respuestas. Debería estar más preocupado por dónde comenzar y cómo enfocarse y en qué concentrarse que tratar de entender cada línea de código de inmediato. Pregúntele a su jefe acerca de las herramientas correctas y las formas de depurar / revisar el código. Este tipo de preguntas te comprarán algunos puntos.

3. De manera regular, acérquese a su jefe para recibir comentarios sobre cómo se está desempeñando, por lo que tendrá una idea de cuál es su porcentaje en términos de percentiles, suponiendo que su jefe haya visto un buen número de personas en la misma situación y tenga un idea de cómo lo hicieron.

4. Aproveche esto como una oportunidad y, a medida que mejore su comprensión del código, siga agregando los comentarios que originalmente esperaba que le hiciera a su jefe.

Si realmente desea intentar pedirle que coloque comentarios en su código (no lo recomiendo), sugeriría encontrar un código que necesite editar que realmente pueda usar algunos comentarios (la mayoría se explica por sí mismo) y preguntar la pregunta acerca de este tema "Estuve viendo este código aquí y estoy tratando de averiguar [problema que está teniendo] y no pude encontrar ningún comentario para ayudar a explicarlo". Básicamente, trate de mostrar que ha hecho un esfuerzo para comprenderlo y explique por qué ambos pueden beneficiarse de los comentarios que se encuentran allí.

Probablemente el 90% del código bien escrito no necesita comentarios. Solo desea documentar las partes del código que se han optimizado y se han vuelto más bien tensas. Trabajé en una empresa una vez que le pedí que documentara cada parte del código que modificó, básicamente, los comentarios terminaron siendo en detrimento de la legibilidad del código porque a menudo se referían al código que se había eliminado o modificado más allá del reconocimiento. Tenga cuidado con los comentarios deficientes. Pasé una semana depurando una función y, al final, descubrí que el comentario que seguí leyendo sobre cómo establecer tal y tal bandera como "falsa" era en realidad todo el problema, puse la bandera en "verdadero" y todo funcionó. como se suponía.

Si desea que los comentarios en el código comprendan por qué se ha escrito algo, lo más probable es que (considerando que es nuevo) todavía no entienda las necesidades comerciales. Estoy seguro de que conoce toda la sintaxis y puede leer el código, pero a menos que sepa el propósito de algún código, entonces se sentirá un poco perdido.

Una cosa que viene a la mente es la programación en pares. Usted dice que su jefe está impresionado con su progreso, por lo que podría sugerirle trabajar junto a él. Esto les ayudará a ambos a largo plazo. Tu jefe tendrá que explicar las cosas que da por sentado y aprenderás más sobre el negocio.

Como han dicho otros, esto es bastante común, pero eso no significa que solo hay que aspirarlo y arar. No es necesario que comprenda la mayor parte del código en la profundidad que cree, y existen estrategias concretas para hacer que el "extremo profundo" sea mucho más superficial:

• Busque algo en el código relacionado con la tarea en cuestión. Por lo general, lo más fácil de buscar es algo visible para el usuario, como la etiqueta del botón en la GUI. Escribe donde lo encontraste. Este será tu punto de anclaje.
• Ahora busque el código a un paso de distancia y escríbalo. ¿Quién crea el botón? ¿A qué código se llama cuando se hace clic en el botón?
• El control de fuente a menudo es útil para encontrar código que está a un paso de distancia. Averigüe cuándo se agregó o cambió el código que está viendo, y vea qué más se registró al mismo tiempo y por qué.
• Repita hasta que entiendas lo suficiente como para hacer tu cambio, más un nivel más profundo para asegurarte de que no te estás perdiendo nada.
• Si te quedas atascado en algún punto, ahora tienes una pregunta muy específica que hacer. Por ejemplo, "No puedo entender de dónde se crea una instancia este botón".

Aquí están mis $ 0.02 en el asunto. No estoy sugiriendo una respuesta exclusiva, mucho de lo que se ha dicho aquí es bastante relevante.

Intentaría un poco de ingeniería social para organizar las cosas de modo que a su jefe le resulte más fácil / menos costoso comentar algo de su código que no hacerlo.

Ahora, esto puede ser bastante fácil si estuvieras dispuesto a arriesgarte y molestarlo, pero no queremos hacerlo. (nota al margen: es posible que no puedas hacer nada sin que él escriba o te dicte comentarios, insistes y lo molestes sin cesar, etc.)

¿Cuál es la alternativa, entonces? Algunas ideas, dependiendo de la circunstancia.

Opción 1

1. Tómese el tiempo para entender una parte de su código como haciendo X.
2. Ahora piense de una manera razonable en que no lo entienda mal .
3. Dígale al jefe (a través del correo electrónico o diga durante el desayuno o lo que no) que actualmente está tratando de averiguarlo.
4. Agregue un comentario que diga que no está claro lo que significa el código, pero lo entiende como Y; intente hacer que este comentario sea visible para él, ¡pero no intente demasiado!
5. Actúe asumiendo Y, y asegúrese de asegurarse de que su jefe se da cuenta de su acción (para que no pierda su tiempo trabajando por un supuesto falso).
6. El jefe debe tomar la iniciativa para corregirte. En este punto, dígale algo como "Realmente deseo que este código tenga un par de comentarios para evitar que haga la suposición errónea. Corregiré el comentario que agregué para mí. Supongo que podría ayudarme con alguna descripción general "¿De este y ese trozo de código? No tengo la experiencia suficiente para descubrir la intención exacta, y solo un par de oraciones servirían". O algo ..

Opción 2

Estás en entrenamiento. Intente organizar una reunión semanal de frecuencia fija (¿adicional?) Con él. En esta reunión, lea un código, pero debe venir lo suficientemente preparado para que no tenga que explicar cada línea. En algún momento, con suerte, se dará cuenta de que puede omitir la reunión si acaba de agregar los comentarios.

Opción 3

Haz que otro compañero de trabajo no entienda el mismo código que tú. Ambos se acercan al jefe en diferentes momentos haciendo las mismas preguntas. Esa es una manera segura de hacerle comprender que no está haciendo algo ... pero no todos tienen el lujo de contar con compañeros de trabajo útiles en el mismo proyecto.

  

Entonces, algo que me ayude a salir hasta que me haga cargo de las cosas, ¿cómo puedo pedirle a mi jefe que ponga comentarios en su código que me da, pero cortésmente?

Si no puede entender el código, ¿por qué cree que los comentarios son su solución?

No conozco su estilo de programación, pero admito que si el nombre de las funciones y las variables son engañosas, es muy difícil entender un código. Pero si los nombres y funciones o incluso la organización del programa (clases, métodos, propiedades ...) son para que el código sea comprensible, entonces el código realmente le hablará por sí solo.

Será mejor que le preguntes por la arquitectura del programa y si quieres pedirle algo, solicita algunos nombres más significativos para las funciones; Eso es más conveniente para él hacer.

Incluso si hay una manera de preguntar esto cortésmente, hay dos posibilidades en cuanto a lo que tu jefe pensará acerca de los comentarios en su código:

1. Cualquier comentario en su código sería bueno tenerlo, o

2. Que los comentarios en su código no sean una buena idea.

Si su jefe piensa que no sería bueno tener comentarios en su código (y existen muy buenos argumentos para esto, es decir, se supone que el código es la documentación , y < em> ninguna documentación estipulará algo tan preciso y tan inequívocamente como el código que realmente lo hace ,) entonces no pasará nada.

Ahora, si por casualidad su jefe cree que los comentarios en su código serían una buena idea, entonces existe una gran posibilidad de que le diga que estudie su código, entienda cómo funciona y continúe agregando comenta a su código usted mismo . (También hay muy buenos argumentos para esto, es decir, necesitas aprender y su tiempo es, por definición, mucho más valioso que el tuyo .)

Entonces, a menos que esté preparado para hacer esto, es mejor que no diga nada.