¿Cómo puedo mejorar al explicar el código a otros desarrolladores? [cerrado]

Si bien la pregunta en sí misma puede sonar tonta, la respuesta es bastante importante para mí, ya que siento que ese problema está afectando negativamente mi rendimiento laboral.

Un poco de los antecedentes aquí: soy un experimentado desarrollador senior de software en un departamento de software de tamaño medio de una compañía que no es de software. Si bien estoy por encima del promedio en el aspecto técnico de las cosas, soy mucho más pobre en comunicar y explicar las cosas. Incluso al explicar algo a otros desarrolladores.

La mayoría de las dificultades ocurren cuando explico cómo funciona un pequeño fragmento de código en particular .

Lo curioso es que explicar y proporcionar ejemplos sobre cómo funciona algo en un nivel mucho más alto, por ejemplo, interacciones entre módulos y subsistemas separados, es mucho más fácil para mí.

Para que quede más claro, lo que yo llamo "habilidad de explicación del código fuente" es un

a) capacidad de explicar claramente el flujo de ejecución del código, por ejemplo, "esta cosa llama a esa cosa, que devuelve ese objeto, que luego llama método A, pasando el objeto B a ..."

a) capacidad de explicar claramente los problemas con un diseño actual o, lo que es más importante, las implicaciones del cambio del código fuente como en "si, por razones de rendimiento, comenzamos a almacenar en caché el objeto como un campo de la clase, tendríamos para realizar modificaciones en diez lugares diferentes para garantizar que el caché esté siempre actualizado ", etc.

Traté de analizar por qué soy malo explicando las cosas y no he encontrado ninguna explicación, excepto tal vez que explique las cosas de una manera muy precisa, lo que algunos pueden encontrar demasiado rígido. Además, cuando explico cosas, tal vez me concentro demasiado en lo que digo y me pierdo las preguntas, lo que la gente hace, pero nuevamente me parece que estas preguntas a menudo son irrelevantes y simplemente arrastran la conversación.

¿Qué me puede recomendar (excepto las obvias "prácticas que lo hacen perfecto", que realmente no compro, ya que creo que probablemente practicaría más de los mismos errores una y otra vez) para que pueda mejorar la fuente Código que explica las habilidades.

Uno de los problemas es que pequeños fragmentos de código no siempre explican el panorama general. Por ejemplo, cuando miro el código fuente desconocido en un lenguaje de programación familiar, generalmente entiendo la mayoría de las declaraciones individuales. Al mismo tiempo, puedo tener dificultades para comprender el algoritmo desconocido al que contribuyen, qué papel desempeña ese algoritmo en la solución completa y por qué se eligió ese algoritmo sobre otras alternativas. En cierto sentido, aunque entiendo esas declaraciones, realmente no las entiendo en absoluto.

Un ejemplo de esto es la clásica función Fast Inverse Square Root .

Algunas cosas que encuentro útiles para lidiar con esto:

• Explique el código en el mismo idioma que usan los usuarios.
• Explique el código usando términos estándar del programador, por ejemplo, términos como "buffer", "list", "singleton" son familiares para la mayoría de nosotros, al igual que los términos matemáticos comunes.
• Explica lo que estás haciendo en términos de entradas y salidas.
• Inventa palabras para conceptos para los que no tienes palabras. A veces uso palabras como "ajustador", "cadena" o "wrangler" como abreviatura de algunos conceptos muy nudosos. Después de todo, así es como se inventaron los términos conocidos en primer lugar.
• Reconozca que, aunque las pocas líneas de código pueden parecer simples en sí mismas, su papel en una base de código más grande puede ser bastante complejo. No siempre se pueden explicar sin proporcionar mucha información de fondo. Si ese es el caso, proporcione.
• Da ejemplos concretos.
• Dibuja diagramas .

El motivo es simple. Piensas como un programador.

Poder explicar conceptos a un alto nivel es lo que hacemos toda nuestra vida cuando queremos transmitir ideas. Sin embargo, cuando programamos, nos ponemos en la mentalidad de que debemos entender cómo hacer las tareas en términos de muchos pasos pequeños y detallados. Explicar eso significa que debe convertir "pasos pequeños y detallados" en algo que cualquiera pueda entender, que no es un pedido pequeño. Si tales cosas fueran fáciles de entender, todos podrían programar. Eso es lo que nos hace programadores.

Sin embargo, como probablemente haya adivinado, una cosa es comprender cómo hacer tareas en términos de muchos pasos pequeños y detallados y otra muy distinta es explicarlas bien.

Yo también he tenido algunas dificultades en este esfuerzo, pero he notado que algunos trucos me han ayudado. Suponga que tiene un método que ha escrito y debe explicar cómo funciona:

• Antes de comenzar con la primera línea, lea su método y recuerde cuál es el alcance, para qué sirve, cuándo se llama y por qué así fue como decidió hacerlo. En resumen, sepa lo que hace. De esta manera, puede responder preguntas de manera exhaustiva y de una manera que abarque el sentido del método (es decir, cuando dicen "No entiendo el punto de esta línea", puede responder: "Esto es lo que crea instancias la conexión a la base de datos utilizada en todo el programa "en lugar de" Eso llama al JDBC que usa la cadena de conexión para establecer una conexión ", que responde a la pregunta pero probablemente no es lo que lo deja claro).
• Explique cada línea del método en términos de lo que cada línea contribuye al propósito general del método. ¿Por qué pusiste esa línea allí? Ah, claro, esta línea llama a la clase responsable de encargarse de la gestión de entrada para verificar si necesitaba delegar acciones en mi ciclo de renderizado.
• Admita cuando su código tal vez no esté claro o pueda mejorarse. Si encuentra código que puede no estar claro, vuelva a escribirlo para que quede más claro. No ayuda la comunicación a frustrar a su compañero programador para que piense que debería estar entendiendo lo que está viendo.

En general, concéntrese en por qué coloca ese código allí en lugar de en lo que hace, y encontrará que sus explicaciones fluirán más fácilmente y serán más fáciles de entender.

También me he encontrado en una posición similar a veces luchando con la explicación del flujo de ejecución del código en un nivel bajo. Lo que me ayudó fue elegir la guía del lenguaje de programación en cuestión (Programación Bjarne Stroustrups en C ++) para actualizarme en cuanto a la terminología que inevitablemente se había desvanecido con los años. Además de leer artículos / blogs relevantes en nuevos idiomas para mantenerse al día con las técnicas / términos actuales.

Con respecto a los problemas / implicaciones de diseño complejo: está bien decir 'No puedo darte una respuesta sin hacer más análisis' sin dar una respuesta inmediata. El software puede volverse muy complejo e incluso los desarrolladores más inteligentes no pueden mantener todas las interacciones en su cabeza todo el tiempo, además, todos somos humanos y hacemos las cosas mal o las perdemos.

Tómese el tiempo para irse y analizar el código para poder estar más seguro de su respuesta. Sin duda, sería mejor que dar una respuesta inmediata, posiblemente mal informada e incorrecta. ¡Desde una posición de desarrolladores sénior, se consideraría una sabiduría e iría a su favor en lugar de parecer receptivo pero potencialmente tonto!