Como posso melhorar a explicação do código para outros desenvolvedores? [fechadas]

Embora a pergunta em si possa parecer boba, a resposta é muito importante para mim, pois sinto que esse problema está afetando negativamente meu desempenho no trabalho.

Um pouco do histórico aqui: sou um desenvolvedor de software sênior experiente em um departamento de software de tamanho médio de uma empresa que não é de software. Embora esteja acima da média no lado técnico das coisas, sou muito mais pobre em comunicar e explicar as coisas. Mesmo ao explicar algo para outros desenvolvedores.

As maiores dificuldades acontecem quando explico como um pequeno pedaço de código funciona.

O engraçado é que explicar e fornecer exemplos de como algo funciona em um nível muito mais alto, por exemplo, interações entre módulos e subsistemas separados, é muito mais fácil para mim.

Para deixar mais claro, o que chamo de "habilidade de explicação do código fonte" é um

a) capacidade de explicar claramente o fluxo de execução do código - por exemplo, "essa coisa chama essa coisa, que retorna esse objeto, que mais tarde chama o método A, passando o objeto B para ..."

a) capacidade de explicar claramente os problemas com um design atual ou, o que é mais importante, implicações da alteração do código fonte como em "se, por razões de desempenho, começarmos a armazenar em cache o objeto como um campo da classe, teríamos para fazer modificações em dez locais diferentes para garantir que o cache esteja sempre no estado atualizado "etc

Tentei analisar por que sou péssimo em explicar as coisas e não encontrei nenhuma explicação, exceto, talvez, que explique as coisas de uma maneira geral, que alguns podem achar muito rígida. Além disso, quando explico as coisas, talvez eu me concentre demais no que digo e na falta das perguntas, no que as pessoas perguntam, mas novamente para mim parece que essas perguntas geralmente são irrelevantes e simplesmente arrastam a conversa para longe.

O que você poderia recomendar (exceto as óbvias "práticas que a tornam perfeita", que eu realmente não compro, pois acho que provavelmente praticaria mais dos mesmos erros repetidamente) para que eu pudesse, para que eu pudesse melhorar a fonte código explicando habilidades.

Um dos problemas é que pequenos pedaços de código nem sempre explicam o quadro geral. Por exemplo, quando olho para o código-fonte desconhecido em uma linguagem de programação familiar, geralmente entendo a maioria das declarações individuais. Ao mesmo tempo, posso ter dificuldade para entender o algoritmo desconhecido com o qual eles contribuem, qual o papel que o algoritmo desempenha na solução completa e por que esse algoritmo foi escolhido em detrimento de outras alternativas. De certa forma, embora eu entenda essas afirmações, realmente não as entendo.

Um exemplo disso é a função clássica Raiz quadrada inversa rápida .

Algumas coisas que acho úteis para lidar com isso:

• Explique o código no mesmo idioma que os usuários usam.
• Explique o código usando termos padrão de programador, por exemplo, termos como "buffer", "lista", "singleton" são familiares para a maioria de nós, assim como termos matemáticos comuns.
• Explique o que você está fazendo em termos de entradas e saídas.
• Invente palavras para conceitos para os quais você não tem palavras. Às vezes, uso palavras como "ajustador", "corrente" ou "wrangler" como abreviação de alguns conceitos muito complicados. Afinal, é assim que termos conhecidos foram inventados em primeiro lugar.
• Reconheça que, embora as poucas linhas de código possam parecer simples em si mesmas, seu papel em uma base de código maior pode ser bastante complexo. Você nem sempre pode explicá-los sem fornecer muitas informações básicas. Se for esse o caso, forneça.
• Dê exemplos concretos.
• Desenhe diagramas .

O motivo é simples. Você pensa como um programador.

Ser capaz de explicar conceitos de alto nível é o que fazemos durante toda a vida quando queremos transmitir idéias. No entanto, quando programamos, nos colocamos na mentalidade de que devemos entender como executar tarefas em termos de muitos passos pequenos e detalhados. Explicar isso significa que você deve converter "etapas pequenas e detalhadas" em algo que alguém possa entender, o que não é uma tarefa pequena. Se essas coisas fossem fáceis de entender, todos poderiam programar. É isso que nos torna programadores.

No entanto, como você provavelmente adivinhou, uma coisa é entender como executar tarefas em termos de várias etapas pequenas e detalhadas e outra é explicá-las bem.

Eu também tive algumas dificuldades nesse empreendimento, mas notei que alguns truques me ajudaram. Suponha que você tenha um método que você escreveu e explique como ele funciona:

• Antes de começar com a primeira linha, leia seu método e lembre-se de qual é o escopo, para qual finalidade ele serve, quando é chamado e por que foi assim que você decidiu fazer isso. Em suma, saiba o que faz. Dessa forma, você pode responder às perguntas de maneira completa e de uma maneira que englobe o sentido do método (ou seja, quando eles dizem "Eu não entendo o objetivo dessa linha", você pode responder: "É isso que instancia a conexão com o banco de dados usado em todo o programa "em vez de" Isso chama o JDBC que usa a cadeia de conexão para estabelecer uma conexão "que responde à pergunta, mas provavelmente não é o que a deixa clara).
• Explique cada linha do método em termos do que cada linha contribui para o objetivo geral do método. Por que você colocou essa linha lá? Ah, claro, essa linha chama a classe responsável por cuidar do gerenciamento de entradas para verificar se eu precisava delegar ações no meu loop de renderização.
• Admita quando seu código talvez não esteja claro ou possa ser melhorado. Se você encontrar um código que não esteja claro, reescreva-o para torná-lo mais claro. Não ajuda a comunicação a frustrar seu colega programador a pensar que ele deveria entender o que está vendo.

Em geral, concentre-se em por que você colocou esse código lá e não no que ele faz, e você descobrirá que suas explicações fluirão mais facilmente e serão mais fáceis de entender.

Também me encontrei em uma posição semelhante às vezes lutando com a explicação do fluxo de execução do código em um nível baixo. O que me ajudou foi pegar o guia da linguagem de programação em questão (Bjarne Stroustrups Programming em C ++) para me atualizar quanto à terminologia que inevitavelmente desapareceu ao longo dos anos. Além de ler artigos / blogs relevantes para o novo idioma para manter-se atualizado com as técnicas / termos atuais.

Com relação a problemas / implicações complexas do projeto: Não há problema em dizer 'Não posso lhe dar uma resposta sem fazer mais análises' sem dar uma resposta imediata. O software pode ficar muito complexo e até os desenvolvedores mais inteligentes não conseguem manter todas as interações na cabeça o tempo todo - além disso, somos todos humanos e entendemos ou sentimos falta das coisas.

Reserve um tempo para ir embora e analisar o código para ter mais certeza da sua resposta. Certamente seria melhor do que dar uma resposta imediata, possivelmente mal informada e errada. Do ponto de vista dos desenvolvedores seniores, isso seria visto como uma sabedoria e seria a seu favor, em vez de parecer responsivo, mas potencialmente tolo!