Meu chefe quer uma explicação narrada linha por linha do código em inglês

Pediram-me especificamente para dar linha por linha (ou conforme apropriado - por exemplo, imagem por imagem, etc.) explicação ou comentário que meu chefe deseja poder ler e seguir.

Como ele não é um programador, ele não pode seguir o código, por isso deseja que tudo seja traduzido para o inglês.

Alguém já foi convidado a fazer isso antes?

Comentei todo o código-fonte e usei o JSDoc para gerar documentação completa de todas as funções, variáveis, etc ... e incluí um exemplo de implementação e demonstrações completas de trabalho com comentários.

Há mais alguma coisa que eu possa fazer para comentar o código para não programadores?

Este não é um pedido razoável, é?

ATUALIZAR

No final, consegui explicar por que não era um bom uso do tempo fazer o que ele estava pedindo. Ele é um cara razoável, e simplesmente não tinha uma compreensão do que meu trabalho envolve. Depois que ele viu esse post, acho que ele entendeu rapidamente que não era um pedido normal.

Forneci documentação adequada para outro programador seguir (JSDoc e comentários em linha - bem como algumas notas extras sobre questões técnicas) e um diagrama de fluxograma muito amplo da lógica principal do programa para o meu chefe seguir.

No final, todas as partes ficaram satisfeitas e seguimos em frente.

Não , não é um pedido razoável!

CONVERSE COM ISSO , ou peça a alguém que o exclua, por todos os meios. Essa é uma ideia irracional, que, embora factível seja tão cara, nunca deveria ser feita. Uma visão geral das funções e sub-rotinas é razoável, mas "explicar" toda linha de código não é. Seria mais eficaz para ele aprender a ler a língua em mãos do que fazer isso.

A próxima coisa que ele pedirá é traduzir fórmulas matemáticas ou outras coisas para o texto em inglês. Embora certamente seja possível, introduza muito espaço para erro e má interpretação e nunca deve ser feito. Assim como "traduzindo" o código para o inglês.

Você tem documentos de design ? Essas são as explicações em inglês do que o código faz. Um gerente que não seja de programação não deve precisar mais do que isso.

Existe um prêmio de micro-gerente do ano? Parece que seu chefe merece uma indicação. Alguém que acredita que precisa entender o código de linha por linha, mas não quer aprender a lê-lo diretamente, é o mais perfeito possível como micro-gerente.

Uma vantagem de ser desenvolvedor é que a dificuldade de entender o código impede o microgerenciamento além de um certo grau, pelo menos no nível detalhado de implementação, pelo menos por um gerenciamento não técnico, porque mesmo o microgerenciador mais rígido reconhece que eles são acima de suas cabeças naquele nível. Mas a genialidade do seu chefe pode encontrar uma maneira de quebrar a cortina de silício.

E, como bônus, gasta uma quantidade enorme de tempo do desenvolvedor fazendo a tradução, mesmo antes de ele usar a tradução em inglês para começar a sugerir várias melhorias (presumo que ele saiba codificar melhor que os programadores, mesmo que ele não possa leia o código e será capaz de compartilhar sua sabedoria assim que alguém o traduzir; caso contrário, por que ele precisaria de todas as linhas traduzidas?).

Portanto, não, não é um pedido razoável, e nunca ouvi falar disso antes. E eu sinto por você. Acho que todo mundo pode precisar procurar silenciosamente outro emprego, porque uma vez que ele começar a usar a tradução de código como ferramenta de gerenciamento, provavelmente será um lugar brutal para se trabalhar (er, um lugar mais brutal para se trabalhar).

No lado positivo, talvez você possa obter um novo anti-padrão com o nome de sua situação? Que tal o antipadrão "Dirty Hungarian Phrasebook", após o esquete de Monty Python, em que uma tabacaria está tentando se comunicar com alguém que não fala inglês usando um livro de frases húngaro que possui traduções falsas?

Sente-se com ele e fale com ele através de 10 linhas do código. Explique todos os detalhes até que ambos concordem que ele entende o quanto deseja.

Talvez essa experiência seja tudo o que ele procura: apenas uma impressão da aparência do seu trabalho e da aparência do software do seu ponto de vista. Isso é bom no meu livro.

Se, depois disso, ele ainda quiser que você continue, diga: observe quantas perguntas eu tive que fazer; imagine se eu tivesse que explicar tudo isso sem poder fazer perguntas, como eu poderia saber o que incluir e o que deixar de fora? Quanto tempo levou para os resultados serem úteis para você? Agora, quantas linhas você quer que eu faça dessa maneira?

Não acho que seja um pedido razoável. O código da fonte não deve ser lido em inglês (ou em qualquer outro idioma).

Talvez ele tenha medo de que você faça seu código fazer algo que ele não aprova ou conhece. Se for esse o caso, acho que não há algo que você possa fazer sobre isso. Você terá que escrever a documentação ou talvez convencê-lo a contratar alguém para auditar seu código.

Realmente é muito simples:

• Você foi contratado por causa de suas habilidades como programador
• Seu gerente não possui essas habilidades
• Portanto, seu gerente não deve razoavelmente esperar poder entender completamente o que você faz

Eu tive uma experiência semelhante a isso em um trabalho anterior. Meu gerente era contador (e, portanto, altamente orientado para detalhes de baixo nível) e não entendia ou não confiava verdadeiramente na programação. Ela não conseguia entender que ela, como pessoa não técnica, não deveria esperar poder entender as minúcias do que escrevi. Depois de muitos pedidos de documentação excessiva e pedidos para treinar usuários não técnicos em como gerenciar e alterar o código (sim, realmente), parei de tentar enganá-la e me recusei totalmente. A analogia que eu costumava explicar era simples:

• Eu não sou contador
• Não espero entender todas as transações ou lançamentos em nossas contas
• Isso não significa que as contas estejam erradas ou não sejam confiáveis, simplesmente porque eu não as entendo
• Isso é possível confiando na pessoa que os compilou

No final de tudo, isso é o que isso soa para mim: um gerente que tem dificuldade em confiar em seus funcionários; ou temores de que eles vão embora e acha que essa é uma maneira eficaz de mitigar isso.

A única solução para isso é sentar e explicar por que isso não faz sentido. É seu trabalho entender o código e possibilitar que alguém com uma habilidade semelhante à sua compreenda, não o de seu gerente. Mostrar a eles esse tópico pode ser uma boa ideia (ou realmente terrível, dependendo da personalidade deles).

Linha por linha, é ridículo. O que eu poderia sugerir é oferecer para gerar documentos a partir de comentários e fornecer isso a ele. Isso foi suficiente para várias concessões e auditorias do governo canadense nas quais trabalhei no passado.

Ele não obtém linha por linha, mas obtém método por método, que ainda deve ter mais granularidade do que precisa.

Algumas soluções existentes, dependendo da sua plataforma:

• C #: castelo de areia
• Java: javadoc
• "C ++, C, Java, Objective-C, Python, IDL (sabores Corba e Microsoft), Fortran, VHDL, PHP, C # e até certo ponto D." : doxygen

Seria muito mais rápido para ele aprender a ler código do que traduzir o código inteiro de qualquer aplicativo interessante para o inglês. Além disso, tentamos isso com o COBOL e não ajudou em nada. Se ele não está disposto a aprender, mas apenas quer tornar sua ignorância o problema de outra pessoa, você tem um chefe seriamente pontudo.

Use seus conhecimentos técnicos para perseguir seu chefe.

1. Faça com que ele saiba que levará tanto tempo para fazer isso quanto para codificá-lo em primeiro lugar (fique à vontade para prolongá-lo).
2. Pergunte a ele como esse documento deve estar atualizado. Informe a ele que todas as alterações de codificação agora levarão pelo menos o dobro do tempo.
3. Se você ou qualquer outra pessoa encontrar algum erro, pergunte a ele se você deve corrigi-lo agora ou aguarde até concluir a codificação psuedo. Lembre-o sobre os nºs 1 e 2.

Como todas as sugestões de soluções ruins, é melhor identificar o problema. Talvez o seu chefe esteja sendo atingido por questões técnicas pela alta gerência e ele se sinta envergonhado, pois não consegue responder. Pode haver uma seção específica do código com a qual ele se sente mais preocupado, para que você possa limitar esse empreendimento massivo a essa área.

Ao enviar uma amostra, ele pode chegar à conclusão de que, se você não entender como a codificação funciona (o que é um loop e o que está fazendo com todos esses itens?), Não importa em que idioma esteja. Ele é melhor fora do entendimento do aplicativo da perspectiva do usuário avançado. Eu acho que é justo que você saiba que você prefere escrever código / dica real - estou procurando outro emprego.

Por quê?

Um comentário linha por linha não é razoável, mas eis o que eu perguntaria: por que você quer isso?

É porque ...

• você quer uma compreensão completa do que o software faz (não necessariamente como)?
• você quer ter certeza de que outro programador pode pegar o projeto se eu sair?
• você quer ver que estou fazendo um trabalho real?

Pode haver um desejo razoável por trás dessa solicitação, e você pode fazer seu chefe feliz descobrindo isso e atendendo a essa necessidade.

Atualizar

Baseado no Mikey'scomentário, talvez eu tenha declarado isso um pouco sem rodeios. Não quero dizer que você deva literalmente dizer "por que você quer isso?", Apenas para descobrir isso . Palavras e tom de voz fazem uma grande diferença. Especificamente, você poderia dizer algo como:

"Eu estive pensando no seu pedido para ter uma explicação de cada linha de código. É um pouco incomum fazer as coisas dessa maneira. Fiquei me perguntando se talvez haja algo que não estou lhe comunicando bem sobre o meu trabalho. O que você realmente quer entender sobre o nosso código ou sobre o que estou fazendo? O que você está tentando realizar aqui? "

Claro, é possível que seu chefe seja totalmente irracional. Mas é mais provável que ele não saiba o quão estranho esse pedido é e tenha algum objetivo racional em mente.

Caso contrário, comece a polir seu currículo. :)

Parece uma boa chance de experimentar a programação alfabetizada. Google it. :)

Mas ... não é necessariamente uma solicitação totalmente irracional. Parte do seu trabalho (a parte mais importante, imo) é comunicar seu (s) algoritmo (s) a outros desenvolvedores e, se necessário, a pessoas não técnicas. Programadores gênios solitários que não conseguem se comunicar são sempre problemáticos, eu acho.

Para esse fim, seu código deve ser muito claro (ou seja: verdadeiramente autodocumentado ou bem documentado, e por "autodocumentado", quero dizer que variáveis ​​e funções têm um significado ou responsabilidade e seus nomes refletem isso claramente). Seu chefe pode ter boas razões para o pedido dele. Talvez (eu estou supondo aqui) você ou seu antecessor tenham uma reputação de código impenetrável e frágil e esse seja o remédio do seu chefe. É um pouco extremo, mas pode ser um exercício útil para você. Suponho que ele saiba que leva tempo para escrever documentos melhores (e, se não o fizer, ele deve ser educado - é como escrever um trabalho: leva mais tempo para escrever do que para ler).

Mesmo uma tradução linha por linha não transmitirá efetivamente o significado de cada linha de código. Os programadores que entendem uma linha de código estão sempre no contexto de muitos fatores. Entre em algo como um pedaço de código multiencadeado e a tradução em inglês não fará mais sentido do que o código bruto. Pense na funcionalidade que está espalhada entre várias funções / arquivos. Algum código não faz absolutamente nenhum sentido sem explicar grandes quantidades de outro código. Tente explicar as diferentes partes envolvidas na injeção de dependência "linha por linha" e você entenderá o que quero dizer. Qualquer coisa que vá além do código processual da função de Deus exigirá uma quantidade extensa de conhecimento de programação apenas para entender a tradução em inglês. Além disso, observe algo tão simples quanto uma declaração de decisão if / else. Não há linha por linha, já que a próxima linha depende dos dados do tempo de execução. A próxima linha pode ser uma das várias possibilidades.Quando você explicar o que seu aplicativo faz, você terá transformado seu PM em programador e ambos terão 5 anos a mais.

Como eu costumava ensinar programação, ficaria muito feliz em tentar.

Ele descobrirá rapidamente que está recebendo mais do que esperava, o que me deixará triste porque eu gosto de explicar as coisas :-)

Quando você se refere ao seu 'chefe', isso é "um gerente intermediário encarregado de você / sua equipe"? ou o proprietário da sua empresa? Você é pago "por hora" ou "com salário"?

Se o seu chefe é um gerente de nível intermediário responsável, CONVERSE COM SEU CHEFE, aponte para que, para atender aos requisitos do seu chefe, sua produtividade para a empresa será reduzida para 1/3 do que poderia ser.

Se o seu chefe é "o cara que assina os cheques", explique a ele a mesma coisa, apenas mais diplomaticamente. Seu trabalho passou de "Escreva o código" para "Escreva o código, escreva a explicação do código, explique a explicação".

Um fluxograma provavelmente será mais benéfico para ele. Este é certamente um pedido incomum e não diz muito sobre ele como gerente.

O fato de seu chefe estar disposto a gastar algum tempo entendendo o código que você escreveu, pode ser usado em seu benefício. Tente apresentá-lo ao Cucumber: http://cukes.info/

e faça seu chefe escrever o teste BDD para você no futuro.

Ele não deveria se preocupar em saber nada disso. Diga a ele que no desenvolvimento de software a implementação está sujeita a alterações. O design do evento está sujeito a alterações. Diga a ele sobre ocultação de informações, encapsulamento e abstração.
Ele, como parte de sua equipe, como cliente do seu código, em um sentido mais amplo, deve trabalhar apenas com uma abstração clara e de alto nível do que seu código faz. Da mesma forma que qualquer camada do seu código funciona com outra camada do código de outra pessoa. Saber mais do que isso, apenas o atrasará, e o risco de fazer suposições com base no funcionamento interno do seu código. Essas suposições deixarão de ser mantidas quando você precisar alterar seu código, o que se torna um problema, se ele criar qualquer tipo de sistema ou processo baseado nelas.
E também ter que fazer esse tipo de trabalho reduzirá sua eficiência. Você não apenas terá que fazer alterações subseqüentes em dois lugares diferentes, mas também terá um impacto negativo no moral do seu trabalho, o que reduzirá ainda mais sua produção.

A beleza do inglês é que é obfucciona lindamente. Se você usar isso a seu favor, poderá nunca mais ter que lidar com esse tipo de solicitação novamente. Eu pegaria um pequeno pedaço do código como um exemplo, mas um que é muito abstrato e nada fácil de entender. Depois, escrevia os comentários em inglês técnico como se você estivesse escrevendo para um capítulo de um livro de programação. Quanto mais longo e mais complicado de seguir, melhor. Diga a ele quantas horas você levou para documentar esse recurso. Explique então que é apenas 1/10 de 1% (use números reais com base em linhas de código, se possível, provavelmente são piores que isso) da base de código real. Quando ele percebe que não tem idéia do que a tradução em inglês diz e que levará 20.000 horas de trabalho para fazer esse nível de documentação, ele recuará rapidamente. Mas esteja muito sinceramente tentando realizar sua tarefa. Não tente fazer isso se você não conseguir fazer isso e ele suspeitar que você está jogando com ele.

Parece um candidato a uma tira especial de Dilbert com cabelos pontudos e questão de férias ! Seu pedido certamente não parece razoável à primeira vista.

Humor à parte, tente descobrir o que ele realmente precisa e por quê, depois aconselhe-o quanto custará em dólares ou horas para lhe dar isso e deixe-o decidir se deseja gastar tanto dinheiro com isso.

Quanto a você, conte as horas que você levará para atender seu pedido aparentemente bizarro e determine se não seria melhor investir uma fração dessa quantidade de tempo na procura de um novo emprego trabalhando para um empregador disposto a tratá-lo como profissional!

Traga-o para o seu escritório e faça um tour pelo seu código.

Ele perceberá, no meio do caminho, que fez uma exigência absurda, e se afastará e nunca mais o incomodará.

Se você não aceitar as exigências dele para ajudá-lo a entender seu código, ele encontrará maneiras diferentes, mas igualmente absurdas, de cutucar você.

É um caso em que a conciliação funciona melhor que a abrasão.

Seria muito bom se tivéssemos um tradutor "Idioma X para inglês" que faça isso. Então alguém poderia sorrir e dizer, sem problemas, chefe, você terá isso em um minuto. E então vem um email com alguns megabytes de texto que diz:

• Seja um novo array inteiro com 20 elementos.
• Seja x uma variável para armazenar números inteiros.
• Defina x como 0
• Enquanto x é menor que 20, faça o que é prescrito nas próximas 2 linhas
• defina o elemento da matriz de a com o índice x para o resultado da chamada nThPrime com o argumento x + 1
• aumentar x em 1
• ....

Outra opção seria sugerir a programação em Shakespeare a partir de agora.

Meu chefe quer uma explicação narrada linha por linha do código em inglês

Difícil.

Como ele não é um programador, ele não pode seguir o código, então quer tudo traduzido para o inglês.

Se ele não é um programador, ele não deve estar lendo o código. Em absoluto.

Forneça documentação de alto nível.

Este não é um pedido razoável, é?

Não.

Como programador, você realmente tem "dois" trabalhos.

O primeiro é criar bons programas. O segundo é "vendê-los" a clientes dentro e fora da empresa.

O pedido do seu chefe "prejudica" o seu primeiro emprego. Leva mais tempo para documentar seus programas. Por outro lado, ele está realmente fazendo você trabalhar mais no seu "segundo" emprego.

Seu chefe está pedindo que você documente seu programa em inglês para o benefício Dele e, presumivelmente, para o benefício das pessoas com as quais ele tem que lidar, dentro e fora da empresa. Se você ajudá-lo a fazer o trabalho dele, isso deve ser benéfico a longo prazo, quando você pedir mais hardware, pessoal ou dinheiro para aumentos. Afinal, ele pediu para você fazer mais trabalho.

Acho que o BDD se encaixaria bem com esse problema, embora pareça que seu projeto esteja quase completo, é meio difícil implementá-lo agora, por isso é mais para referência futura.

Com o BDD, os casos de uso são descritos como documentos legíveis por humanos que são convertidos em testes funcionais automatizados.

Provavelmente, esse pedido é um bom momento para aprender coisas como o ANTLR . Pegue o ANTLR, pegue a gramática do seu idioma, analise todo o código que você possui, percorra o seu AST gerando descrições baseadas em modelo para cada nó, i++como descrito em increase i by 1 using postfix increment operator. Isso deve ser muito engraçado. Seu chefe também pode querer que essa ferramenta seja incluída no script de compilação; assim, toda vez que você fizer alterações, ele receberá um e-mail de ~ 20 MB descrevendo o que a nova versão faz.

PS Brincadeira, ele é um idiota.

Embora eu concorde que essa seja uma solicitação irracional, seu chefe pode apreciar algo como a saída da Docco , que separa seu código e comentários linha a linha ou cláusula por cláusula em saída HTML de duas colunas, com o código em uma lado e prosa, por outro. Você tem que digitar os comentários você mesmo, é claro, mas a apresentação é muito boa, mesmo para leitores não técnicos. Consulte, por exemplo, uma seção comentada linha a linha do código anotado para Underscore.js . Existem também versões de scripts Python e shell.

É possível que seu chefe esteja desinformado e intimidado, mas na verdade seja uma pessoa razoável. Nesse caso, o raciocínio com ele pode funcionar - uma conversa casual em que você promete fornecer "o que ele realmente quer", ou seja; um guia em prosa sobre o que o programa está fazendo.

Se tudo se resume a "meu caminho ou a estrada", verifique melhor o seu combustível agora.

Você poderia escrever alguns testes de aceitação usando uma estrutura de design orientada a comportamento, como pepino ? Isso não explica o código; explicará o que faz e em linguagem natural. Ele também tem a vantagem de ser executável, para que você sempre possa ter certeza de que a documentação está atualizada, pois, se não estiver, o executor de teste ficará vermelho.

Confira o vídeo de introdução. Talvez seja uma boa diversão enquanto você encontra um novo chefe ... ;-)

Seu gerente está quase certamente angustiado pelo fato de não entender o que as pessoas fazem e que ele está gerenciando, e ele não tem experiência para entender os resultados que elas produzem.

Duvido que ele tenha pensado nessa solução completamente, e provavelmente lhe pareceu sensato à primeira vista. Mas isso ocorre principalmente porque ele não entende o que realmente é o código de programação.

Qualquer programador entende o absurdo dessa solicitação, mas sabemos porque intuitivamente sabemos que depois que você passa pela linguagem, tudo o que é revelado é o algoritmo, que é igualmente enigmático.

// 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

O problema aqui é que, embora os comentários expliquem o que cada linha faz, você ainda não tem idéia do que o código realmente faz, a menos que compreenda quais são todas as implicações. É óbvio se você é um programador e já viu esse padrão antes; mas mostre isso a alguém que apenas entende de vendas e ele ficará tão confuso depois de ler os comentários quanto antes.

Você pode economizar tempo ensinando ao seu chefe alguma programação básica. Se ele quiser ler seu código, dê a ele as ferramentas para poder fazer isso. A maioria dos idiomas é bastante compacta quanto à sintaxe, e o aprendizado da estrutura leva apenas uma ou duas horas. Ele quase desistirá depois de alguns dias, mas pelo menos saberá o que está passando e, mais importante ainda, por que não quer ler seu código.

IMHO ... se ele é responsável por realizar a tarefa, ele deve saber como funciona ... :)