O que é o código de auto-documentado e ele pode substituir bem documentado código? [fechadas]

Question

Eu tenho um colega que insiste que seu código não precisa de comentários, é "auto documentar."

Eu revi o seu código, e enquanto é mais clara do que o código que eu vi outros produzem, eu ainda discordar de que código de auto-documentando é tão completo e útil bem comentado e código documentado.

me ajudar a entender sua ponto de vista.

• O que é código de auto documentando
• Pode realmente substituir bem comentado e código documentado
• Existem situações em que é melhor do que bem documentado e código comentado
• Existem exemplos em que o código não pode ser auto-documentado sem comentários

Talvez seja apenas minhas próprias limitações, mas eu não vejo como ele pode ser uma boa prática.

Isto não pretende ser um argumento - por favor não trazer razões pelas quais bem comentado e código documentado é alta prioridade - há muitos recursos que mostram isso, mas eles não são convincentes para o meu par. Eu acredito que eu preciso entender mais plenamente a sua perspectiva para convencê-lo de outra forma. Iniciar uma nova pergunta se você tem, mas não discuto aqui.

Wow, resposta rápida! Por favor, leia todas as respostas existentes e fornecer comentários para respostas ao invés de adicionar novas respostas, a menos que a sua resposta realmente é substancialmente diferente de qualquer outra resposta aqui.

Além disso, aqueles de vocês que estão argumentando contra código de auto documentando -este é principalmente para me ajudar a entender a perspectiva (ou seja, aspectos positivos) de evangelistas código de auto-documentar. Espero que outros vão downvote você, se você não ficar no tópico.

Answer 1

Na minha opinião, qualquer código deve ser auto-documentado. Na boa, código de auto-documentado, você não tem que explicar cada linha, porque cada identificador (variável, método, classe) tem uma clara semântica nome. Ter mais comentários do que o necessário na verdade torna mais difícil (!) Para ler o código, por isso, se o seu colega

• escreve comentários de documentação (Doxygen, JavaDoc, comentários XML etc.) para cada classe, membro, tipo e método E
• comenta claramente as partes do código que são não autodocumentados E
• escreve um comentário para cada bloco de código que explica a intenção, ou que o código faz em um nível de abstração mais elevado (ou seja, encontrar todos os arquivos maiores que 10 MB em vez de percorrer todos arquivos em um diretório, teste se o tamanho do arquivo é maior do que 10 MB, o retorno de rendimento se for verdade )

seu código e documentação é bom, na minha opinião. Note-se que código de auto-documentada faz não significa que não deve haver comentários, mas apenas que não deve haver comentários desnecessários. A coisa é, porém, que através da leitura do código (incluindo comentários e comentários de documentação) deve render uma compreensão imediata de que o código faz e porquê. Se o código "auto-documentando" leva mais tempo para entender do que código comentado, não é realmente auto-documentado.

Answer 2

Bem, já que trata-se de comentários e código, Vamos olhar algum código real. Compare este código típico:

float a, b, c; a=9.81; b=5; c= .5*a*(b^2);

Para este código de auto-documentação, o que mostra o está sendo feito:

const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

E, em seguida, a este código documentado, que explica melhor por que está sendo feito:

/* compute displacement with Newton's equation x = vₒt + ½at² */
const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

E a versão final do código como documentação com zero comentários necessário:

float computeDisplacement(float timeInSeconds) {
    const float gravitationalForce = 9.81;
    float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);
    return displacement;
}

Aqui está um exemplo de um estilo comentando pobres:

const float a = 9.81; //gravitational force
float b = 5; //time in seconds
float c = (1/2)*a*(b^2) //multiply the time and gravity together to get displacement.

No último exemplo, os comentários são utilizados quando as variáveis ??deveria ter sido descritiva chamado em vez disso, e os resultados de uma operação são resumidos quando podemos ver claramente que a operação é. Eu preferiria o segundo exemplo de auto-documentada a esta qualquer dia, e talvez isso é o que seu amigo está falando quando diz código de auto-documentada.

Eu diria que isso depende do contexto do que você está fazendo. Para mim, o código de auto-documentado é provavelmente suficiente neste caso, mas um comentário detalhando a metodologia por trás do que está por trás feito (neste exemplo, a equação) também é útil.

Answer 3

O código em si é sempre vai ser a explicação mais up-to-date do que o seu código faz, mas na minha opinião é muito difícil para ele para explicar intenção , que é o mais importante aspecto dos comentários. Se está escrito corretamente, já sabemos o o código faz, só precisamos de saber porque na terra ele faz isso!

Answer 4

Alguém disse uma vez

1) Apenas comentários de escrita para o código que é difícil de entender.
2) Tente não escrever código que é difícil de entender.

Answer 5

A idéia por trás do código "auto-documentado" é que a lógica do programa actual no código é suficiente trivialmente claro para explicar para quem lê o código não só o que o código está fazendo, mas por que ele está fazendo isso.

Na minha opinião, a idéia de código verdadeiro auto-documentado é um mito. O código pode dizer que a lógica por trás do que está acontecendo, mas ela não pode explicar por que está sendo feito de uma certa maneira, particularmente se houver mais do que uma maneira de resolver um problema. Só por isso nunca pode substituir bem comentado código.

Answer 6

Eu acho que é relevante para a questão de saber se uma determinada linha de código é auto-documentado, mas no final, se você não entender a estrutura e função de uma fatia de código, em seguida, a maioria dos comentários de tempo não vai ajudar. Tomemos, por exemplo, uma fatia de amdfan de "corretamente comentado" código:

/* compute displacement with Newton's equation x = v0t + ½at^2 */
const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

Este código é bom, mas a seguinte é igualmente informativo na maioria dos sistemas de software modernos, e explicitamente reconhece que o uso de um cálculo newtoniano é uma escolha que pode ser alterada devem algum outro paradigma físico ser mais apropriado:

const float accelerationDueToGravity = 9.81;
float timeInSeconds = 5;
float displacement = NewtonianPhysics.CalculateDisplacement(accelerationDueToGravity, timeInSeconds);

Na minha própria experiência pessoal, há muito poucas situações de codificação "normais", onde é absolutamente necessário comentários. Quantas vezes você acaba rolando seu próprio algoritmo, por exemplo? Basicamente tudo o resto é uma questão de estruturação seu sistema para que um programador pode compreender as estruturas em uso e as escolhas que levaram o sistema a usar essas estruturas particulares.

Answer 7

Eu esqueço de onde eu tirei isso, mas:

Cada comentário em um programa é como um pedido de desculpas ao leitor. "Lamento que o meu código é tão opaco que você não pode compreendê-lo, olhando para ela". Nós apenas temos que aceitar que não somos perfeitos, mas se esforçar para ser perfeito e ir direito em pedir desculpas quando precisamos.

Answer 8

código de auto-documentado é um bom exemplo de "seca" (Do not Repeat Yourself). Faça informação não duplicado nos comentários o que é, ou pode ser, no próprio código.

Ao invés de explicar o que uma variável é usada para, mudar o nome da variável.

Ao invés de explicar o que um pequeno trecho de código faz, extraí-lo em um método e dar-lhe um nome descritivo (talvez uma versão abreviada do seu comentário de texto).

Ao invés de explicar o que um teste complicado faz, extrato que em um método muito e dar-lhe um nome bom.

Etc.

Após isso, você acabar com código que não exigem tanta explicação, explica-se, por isso você deve eliminar os comentários que a informação meramente repetição no código.

Isto não significa que você tem comentários em tudo, há algumas informações que você não pode colocar no código, como informações sobre a intenção (o "porquê"). No caso ideal o código e os comentários se complementam, cada adição de valor explicativo única sem duplicar a informação na outra.

Answer 9

código de auto-documentação é uma boa prática e, se feito corretamente pode facilmente transmitir o significado do código sem ler muitos comentários. especialmente em situações onde o domínio é bem compreendido por todos na equipe.

Dito isto, os comentários podem ser muito úteis para recém-chegados ou para testadores ou para gerar arquivos de documentação / ajuda.

código de auto-documentando + observações necessárias irá percorrer um longo caminho no sentido de ajudar as pessoas entre as equipes.

Answer 10

Em primeiro lugar, é bom saber que o código do seu colega é na verdade mais clara do que outro código que você já viu. Isso significa que ele provavelmente não está usando "auto-documentado" como uma desculpa para estar com preguiça de comentar seu código.

código de auto-documentando é um código que não necessita de comentários de texto livre para um leitor informado para entender o que está fazendo. Por exemplo, este pedaço de código é auto-documentado:

print "Hello, World!"

e assim é esta:

factorial n = product [1..n]

e assim é esta:

from BeautifulSoup import BeautifulSoup, Tag

def replace_a_href_with_span(soup):
    links = soup.findAll("a")
    for link in links:
        tag = Tag(soup, "span", [("class", "looksLikeLink")])
        tag.contents = link.contents
        link.replaceWith(tag)

Agora, essa idéia de um "leitor informado" é muito subjetivo e situacional. Se você ou alguém está tendo problemas para seguir o código do seu colega, então ele faria bem para re-avaliar a sua ideia de um leitor informado. Algum nível de familiaridade com a linguagem e as bibliotecas que está sendo usado deve ser assumida, a fim de código de chamada auto-documentado.

O melhor argumento que eu vi para escrever "código de auto-documentando" é que ele evita o problema de comentário de texto livre não concordar com o código como está escrito. A melhor crítica é que enquanto o código pode descrever o e como que está fazendo por si só, não pode explicar por algo está sendo feito de uma certa maneira .

Answer 11

Em ordem:

• código de auto-documentado é o código que expressa claramente sua intenção para o leitor.
• Não inteiramente. Comentários são sempre úteis para comentários no por uma estratégia particular foi escolhido. No entanto, os comentários que explicam o uma seção de código está fazendo são indicativos de código que não é suficientemente auto-documentado e poderia usar alguma refatoração ..
• Comentários mentir e ficar fora de data. Código sempre conta é mais propensos a dizer a verdade.
• Eu nunca vi um caso em que o o do código pode não ser suficientemente claro, sem comentários; no entanto, como eu disse anteriormente, às vezes é necessário / útil incluir comentário sobre o por .

É importante notar, no entanto, que o código realmente auto-documentando tem um monte de auto-regulação e equipa-disciplina. Você tem que aprender a programar mais declarativa, e você tem que ser muito humilde e evite código "inteligente" em favor de código que é tão óbvio que parece que qualquer um poderia tê-lo escrito.

Answer 12

Por um lado, considere o seguinte trecho:

/**
 * Sets the value of foobar.
 *
 * @foobar is the new vaue of foobar.
 */
 public void setFoobar(Object foobar) {
     this.foobar = foobar;
 }

Neste exemplo você tem 5 linhas de comentários por 3 linhas de código. Pior ainda - os comentários não acrescentam nada que você não pode ver através da leitura do código. Se você tem 10 métodos como este, você pode obter 'comentário cegueira' e não notar a um método que se desvia do padrão.

Se claro, uma versão melhor seria:

/**
 * The serialization of the foobar object is used to synchronize the qux task.
 * The default value is unique instance, override if needed.
 */
 public void setFoobar(Object foobar) {
     this.foobar = foobar;
 }

Ainda assim, para o código trivial Eu prefiro não ter comentários. A intenção e a organização geral é melhor explicada em um documento separado fora do código.

Answer 13

Quando você lê um "código de auto-documentação", você vê o que está fazendo, mas você não pode sempre adivinhar por que ele está fazendo dessa maneira particular.

Há toneladas de restrições não-programação como a lógica de negócios, segurança, demandas dos usuários etc.

Quando você fazer a manutenção, as informações backgorund-se muito importante.

Apenas minha pitada de sal ...

Answer 14

Uma coisa que você pode querer chamar a atenção para o seu colega é que não importa o quão auto-documentar seu código é, se outras abordagens alternativas foram consideradas e descartadas essa informação vai se perder, a menos que ele comenta o código com essa informação. Às vezes é tão importante saber que uma alternativa era considerado e por isso foi decidido contra e comentários de código são mais propensos a sobreviver ao longo do tempo.

Answer 15

Você já ouviu falar do projeto de Donald Knuth "WEB" para implementar o seu Alfabetizado Programação conceito ? É mais do que código de auto-documentando; é mais como documentação que pode ser compilado e executado como código. Eu não sei o quanto isso é usado hoje embora.

Answer 16

A diferença é entre "o que" e "como".

• Você deve documentar "o que" uma rotina faz.
• Você não deve documentar "como" ele faz isso, a não ser casos especiais (por exemplo, referem-se a um papel de algoritmo específico). Isso deve ser auto-documentada.

Answer 17

Em uma empresa onde eu trabalhava um dos programadores tinham a seguinte preso ao topo de seu monitor.

"Documente seu código como a pessoa que mantém é um maníaco homocidal quem sabe onde você vive."

Answer 18

O ponto de vista que o código é discos documentar auto-me louco. Uma determinada linha de código ou um algoritmo de sub pode ser de fato auto documentando mas de propósito no maior picutre simplesmente não é.

Eu fiquei tão frustrado com isso um ou dois meses atrás eu escrevi todo um post descrevendo o meu ponto de vista. Poste aqui .

Answer 19

código de auto-documentando normalmente usa nomes de variáveis ??que correspondem exatamente o que o código está fazendo de modo que é fácil de entender o que está acontecendo

No entanto, tal "código de auto-documentando" nunca vai substituir comentários. Às vezes o código é muito complexo e código de auto-documentação não é suficiente, especialmente no modo de manutenção.

Uma vez tive um professor que era um crente firme nessa teoria Na verdade, a melhor coisa que já me lembro dele dizendo é "Comentários são para maricas"
Levou todos nós de surpresa no início, mas faz sentido.
No entanto, a situação é que mesmo que você pode ser capaz de entender o que está acontecendo no código, mas alguém que é menos experiente que você pode vir atrás de você e não entender o que está acontecendo. Isto é, quando observações se tornam importantes. Eu sei que muitas vezes que nós não acreditamos que eles são importantes, mas existem muito poucos casos onde os comentários são desnecessários.

Answer 20

Estou surpreso que ninguém trouxe " Alfabetizado Programação ", uma técnica desenvolvida em 1981 por Donald E. Knuth de TeX e "The Art of Computer Programming" fama.

A premissa é simples: uma vez que o código tem de ser entendida por um ser humano e os comentários são simplesmente jogados fora pelo compilador, por que não dar a todos a coisa que eles precisam - uma descrição textual completa da intenção do código, sem restrições por programação requisitos linguísticos, para o leitor humano e código puro para o compilador.

ferramentas de programação literate fazer isso, dando-lhe marcação especial para um documento que informa as ferramentas que parte deve ser fonte e qual é texto. O programa depois rasga as partes do código-fonte para fora do documento e monta um arquivo de código.

Eu encontrei um exemplo na web dele: http://moonflare.com/code /select/select.nw ou a versão HTML http://moonflare.com/ código / select / select.html

Se você pode encontrar o livro de Knuth sobre ele em uma biblioteca (Donald E. Knuth, Programação Alfabetizado, Stanford, Califórnia:. Centro para o Estudo da Linguagem e Informação, 1992, CSLI Lecture Notes, não 27.) você deve ler -lo.

Isso é código de auto-documentação, completa com o raciocínio e tudo. Mesmo torna um documento legal, Tudo comentários resto é apenas bem escrito: -)

Answer 21

A minha visão está escrito neste post:

A uma única dica para documentar seu código.

Trecho:

Em vez de escrever um monte de comentários para explicar os comportamentos sutis de seu programa, porque não reestruturar a sua lógicas de modo que eles são auto-evidentes? Em vez de documentar o que um método está fazendo, por que não escolher um nome claro para esse método? Em vez de marcação seu código para indicar obra inacabada, porque não basta lançar uma NotImplementedException ()? Ao invés de se preocupar se seus comentários soam educados o suficiente para seu chefe, seu colegas ou qualquer um que lê o código, porque não basta parar de se preocupar por não escrevê-los em tudo?

A mais clara o seu código, mais fácil é mantê-la, a alargá-la, a trabalhar com ele em edições futuras. o menos ordorous é o seu código, a menos necessidade há para comentar isso. O mais os comentários, maior a maintanence custo.

Answer 22

Eu gostaria de oferecer mais uma perspectiva para as muitas respostas válidas:

O que é código-fonte? O que é uma linguagem de programação?

As máquinas não precisa de código fonte. Eles estão felizes em execução montagem. linguagens de programação são para o nosso benefício. Não quero escrever montagem. Precisamos entender o que está escrevendo. A programação é sobre a escrita de código.

Caso você seja capaz de ler o que você escreve?

código

Fonte não está escrito em linguagem humana. Ele foi tentado (por exemplo, Fortran), mas não é completamente bem sucedido.

código

Fonte não pode ter ambiguidades. É por isso que temos de colocar mais estrutura nele do que fazemos com o texto. Texto só funciona com o contexto, que nós tomamos para concedido quando usamos texto. Contexto em código fonte é sempre explisit. Pense "usando" em C #.

A maioria das linguagens de programação têm redundância para que o compilador pode nos pegar quando não são coerentes. Outros idiomas utilizam mais de inferência e tentar eliminar essa redundância.

Os nomes de tipo, nomes de métodos e nomes de variáveis ??não são necessários pelos computadores. Eles são usados ??por nós para fazer referência. O compilador não entende a semântica, que é para nós usarmos.

Linguagens de programação são uma ponte lingüística entre homem e máquina. Tem que ser gravável para nós e legível para eles. demandas secundárias são de que ele deve ser legível para nós. Se nós somos bons em semântica, onde permitido e bom em estruturação do código, código de fonte deve ser fácil de ler, mesmo para nós. A melhor código não precisa de comentários.

Mas se esconde a complexidade de cada projeto, você sempre tem que decidir onde colocar a complexidade, e que os camelos de engolir. Esses são os lugares para usar comentários.

Answer 23

código documentação Self é uma opção fácil para o problema, que o código ao longo do tempo, comentário e documentação divergem. E é um fator disciplinador para escrever código claro (se você é que o estrito sobre si mesmo).

Para mim, estas são as regras que tentam seguir:

• Código deve ser tão fácil e clara para ler quanto possível.
• Os comentários devem dar razões para projetar decisões que tomei, como: por que eu uso esse algoritmo, ou limitações do código tem, como: Será que Não trabalho quando ... (este deve ser tratadas de um contrato / afirmação em o código) (geralmente dentro da função / procedimento).
• A documentação deve listar a utilização do (Chamando converntions), lado efeitos, possíveis valores de retorno. isto pode ser extraído a partir do código usando ferramentas como jdoc ou xmlDoc. isto Por conseguinte, geralmente é fora do função / procedimento, mas perto do Código que descreve.

Isto significa que todos os três meios de documentar o código ao vivo juntos e, portanto, são mais propensos a ser alterado quando as alterações de código, mas não se sobrepõem no que eles expressam.

Answer 24

O problema real com o código de chamada auto-documentando é que ele transmite o que ele realmente faz. Enquanto alguns comentários podem ajudar alguém entender o código melhor (por exemplo, algoritmos etapas, etc.) que é um redundante grau e eu duvido que você iria convencer o seu par.

No entanto, o que é realmente importante na documentação é o material que não é diretamente evidente a partir do código: subjacentes intenção, suposições, impactos, limitações, etc.

Ser capaz de determinar que um código faz X a partir de uma rápida olhada é a maneira mais fácil do que ser capaz de determinar que um código não faz Y. Ele tem que documentar Y ...

Você poderia mostrar-lhe um exemplo de um código que parece bem, é óbvio, mas na verdade não cobrir todas as bases da entrada, por exemplo, e ver se ele acha.

Answer 25

Eu acho que o código de auto-documentando é um bom substituto para comentar. Se você precisar de comentários para explicar como ou por código é do jeito que é, então você tem uma função ou nomes de variáveis ??que devem ser modificados para ser mais explicativo. Pode ser até o codificador para saber se ele vai compensar o déficit com um comentário ou renomear algumas variáveis ??e funções e refatoração de código embora.

Ele não pode realmente substituir a documentação, porém, porque a documentação é o que você dá aos outros para explicar como usar o sistema, ao invés de como ele faz as coisas.

Edit: eu (e provavelmente todos os outros) provavelmente deve ter a disposição que um aplicativo de processamento de sinal digital (DSP) deve ser muito bem comentado. Isso é principalmente porque aplicativos DSP são essencialmente 2 loops alimentados com matrizes de valores e adiciona / multiplica / etc referidos valores ... para alterar o programa que você alterar os valores em uma das matrizes ... precisa de um par de comentários para dizer o que você está fazendo nesse caso;)

Answer 26

Ao escrever código matemático, eu descobri, por vezes, útil para escrever longos, ensaístico comentários, explicando a matemática, as convenções de notação os usos de código, e como tudo se encaixa. Estamos falando de centenas de linhas de documentação, aqui.

Eu tento fazer o meu código de auto-documentado quanto possível, mas quando eu voltar a trabalhar com ele depois de alguns meses, eu realmente necessidade de ler a explicação para não fazer um hash de fora.

Agora, é claro que este tipo de medida extrema não é necessário para a maioria dos casos. Eu acho que a moral da história é: código diferente requer diferentes quantidades de documentação. Algum código pode ser escrito de forma tão clara que ele não precisa de comentários - assim escrevê-lo que claramente e não use comentários lá

Mas muitas código faz comentários precisam fazer sentido, então escrevê-lo tão claramente quanto possível e depois usar como muitos comentários como ele precisa ...

Answer 27

Eu diria - como muitos de vocês - que, para ser verdadeiramente auto documentar, necessidades de código para mostrar algum tipo de intenção. Mas estou surpreso que ninguém mencionou BDD ainda - Behavior Driven Development . Parte da idéia é que você tem testes automatizados (código) explicando a intenção de seu código, que é tão difícil fazer óbvio contrário.

Good domain modeling 
+ good names (variabes, methods, classes) 
+ code examples (unit tests from use cases) 
= self documenting software 

Answer 28

Um par de razões pelas quais comentários extras, além do código pode ser mais claro:

• O código que você está olhando foi gerado automaticamente e, portanto, quaisquer edições ao código pode ser derrotado na próxima vez que o projeto é compilado
• A menos do que simples implementação foi negociado fora para um ganho de desempenho (desenrolando um loop, criando uma tabela de referência para um cálculo caro, etc.)

Answer 29

O seu vai ser tudo em quais são os valores da equipe em sua documentação. Gostaria de sugerir que documentar porquê / intenção em vez de como é importante e isso nem sempre é capturado no código de auto documentar. se / não definir essas são óbvios - mas o cálculo, recuperação etc algo do por que deveria ser expressa.

Também estar ciente da diferença em sua equipe, se você está vindo de diferentes nacionalidades. Diferenças na dicção pode creap para a nomeação de métodos:

BisectionSearch

BinarySearch

BinaryChop

Estes três métodos contribuíram de desenvolvedores capacitados em 3 continentes diferentes fazer a mesma coisa. Apenas lendo os comentários que descrevem o algoritmo fomos capazes de identificar a duplicação na nossa biblioteca.

Answer 30

Para mim leitura de código que precisa de comentários é como ler texto no idioma Eu não sei. Vejo declaração e eu não entendo o que ele faz ou por que - e eu tenho de olhar para comentários. Eu li uma frase e eu preciso olhar no dicionário para entender o que isso significa.

Geralmente é fácil de escrever código que a auto-documentos que ele faz. Para dizê-lo porque ele faz isso comentários são mais adequado, mas mesmo aqui código pode ser melhor. Se você entender o sistema em todos os níveis de abstração, você deve tentar organizar-lhe um código como

public Result whatYouWantToDo(){
  howYouDoItStep1();
  howYouDoItStep2();
  return resultOfWhatYouHavDone;
}

Onde nome do método reflete seu corpo intenção e método explica como você atingir o seu objetivo. Você mesmo assim não posso dizer livro inteiro em seu título, assim principais abstrações do seu sistema ainda tem que ser documentado, bem como algoritmos complexos, contratos de métodos não-triviais e artefatos.

Se o código que seu produc colega é realmente auto-documentada - de sorte que você e ele. Se você acha que seu código colegas precisa de comentários - ele precisa. Basta abrir o lugar mais não-trivial nele, lê-lo uma vez e ver se você entendeu tudo ou não. Se o código é auto-documentado - então você deve. Se não - pergunte ao seu colega uma pergunta sobre isso, depois que ele lhe dá uma resposta perguntar por que essa resposta não foi documentado em comentários ou código de antemão. Ele pode afirmar que o código é auto-documento para tal pessoa inteligente como ele, mas mesmo assim tem que respeitar os outros membros da equipe - se suas tarefas requerem a compreensão de seu código e seu código não explicar-lhe tudo o que você precisa entender - ele precisa comentários.