Você acha que o código é auto-documentado? [fechadas]

Essa é uma pergunta que me foi feita há muitos anos como graduada em uma entrevista de emprego e que está incomodando meu cérebro de vez em quando e nunca encontrei realmente uma boa resposta que me satisfizesse.

O entrevistador em questão estava procurando uma resposta em preto e branco, não havia meio termo. Eu nunca tive a chance de perguntar sobre a lógica por trás da pergunta, mas estou curioso para saber por que essa pergunta seria feita a um desenvolvedor e o que você aprenderia com uma resposta sim ou não?

Do meu próprio ponto de vista, eu posso ler Java, Python, Delphi, etc., mas se meu gerente vier até mim e me perguntar quanto tempo estou em um projeto e digo "O código está 80% completo" (e antes você começa a me abater, ouvi isso proferido em alguns escritórios pelos desenvolvedores), como exatamente isso é auto-documentado? Desculpas se essa pergunta parecer estranha, mas eu prefiro perguntar e obter algumas opiniões sobre ela para entender melhor por que ela seria apresentada a alguém em uma entrevista.

Parcialmente.

O código que usa grandes palavras em inglês pode ser parcialmente auto-documentado, pois os nomes de todas as funções e variáveis ​​podem indicar o que está fazendo. Mas provavelmente não vai lhe dizer o porquê.

Comparar:

a->b;
# what is b doing? what is the a object?

carEngine->startIgnition;
# much more clear what objects are involved

Mas você ainda não sabe por que um carro está sendo iniciado. Portanto, apenas parcialmente. É meio terrível que seu entrevistador esteja esperando uma resposta em preto e branco, a menos que sua visão de preto e branco inclua um talvez muito forte.

Não. O código em si não é auto-documentado.

A razão é que o código declara COMO e não se importa com POR QUE, o que os humanos precisam saber para manter o código.

Portanto, você precisa de comentários adicionais explicando todos os PORQUES . Você pode limitá-los, deixando que os nomes de suas variáveis ​​incluam parte das decisões, mas não pode evitá-los.

O código adequado informa " como ". Comentários adequados dizem " por que " .

Portanto, o código pode ser auto-documentado da maneira como as coisas são alcançadas, mas você não pode assumir que ele documenta o motivo.

Se eles insistem em uma resposta em preto e branco sem o meio termo permitido, a resposta é não.

A resposta mais completa é que o código deve ser auto-documentado na extensão máxima que for razoável, mas não há uma maneira razoável de incluir alguns tipos de documentação no código. Apenas por exemplo, o código pode ajudar bastante a documentar quais informações são coletadas no formulário A, no formulário B e no formulário C. Geralmente, ele não tenta (e provavelmente não deve) tentar documentar testes mostrando essa divisão os dados dessa maneira reduziram os erros x% em comparação com (por exemplo) usando apenas dois formulários em vez de três.

Qualquer coisa, exceto a parte mais trivial do código, pode se beneficiar de pelo menos alguma documentação externa.

Minha resposta. Na maior extensão possível, você deve se esforçar para tornar seu código o mais documentado possível. Há muitas razões para isto. Quando inicialmente escrito, uma média de uma linha em 10 tem um erro. Erros no código tendem a ser encontrados e corrigidos. Erros na documentação tendem a ser deixados. E na manutenção, é comum que o código e a documentação se afastem.

Dito isto, existem limitações para o que pode ser feito, tornando o código claro. Nesses casos, você deve documentar.

E o caso em que você tem a opção de documentar? Minha opinião é que a manutenção depende muito da sua organização. Se você possui excelentes desenvolvedores de software e um rigoroso processo de revisão de código (como, por exemplo, o Google), seu processo e as pessoas podem ser de tal ordem que você não precisa se preocupar tanto com os comentários que não são mantidos. Nesse caso, um estilo muito mais pesado de comentários faz muito sentido. (O Google, de fato, tem um estilo pesado de comentários.) No entanto, se você tem uma organização mais típica, desconfio muito de qualquer comentário que vejo e espero que você tenha pessoas que acreditem na tentativa de tornar o código auto-documentado. Nessa situação, considerarei os comentários supérfluos.

Para uma conversa interessante sobre os méritos e as desvantagens de comentar, consulte http://www.perlmonks.org/index.pl?node_id=65153 para uma conversa antiga da qual participei. (Observe que, ao mesmo tempo em que tivemos essa conversa, houve um conjunto particular de bate-papos mais amigáveis. Sempre lamento que apenas a metade mais negativa da conversa seja pública.) Minhas opiniões não correspondem mais exatamente ao que eu pensava na época. , mas ainda acho que a conversa vale a pena refletir.

Acho que essa pergunta surge muito e muitas vezes tem um fervor religioso a respeito. Aqui está a minha opinião sobre isso ...

Em um mundo ideal, a seguinte declaração pode ser feita:

O código deve ser escrito de tal maneira que a lógica possa ser seguida sem a necessidade de comentar.

OK, isso é justo o suficiente, mas o problema é que não vivemos em um mundo ideal. Existem alguns problemas para alcançar essa afirmação ideal.

1. Os programadores geralmente não são os especialistas do setor em que estão programando. É fácil entender uma função como startEngine(Car car)(a maioria) todos podem entender o que está sendo solicitado aqui. Mas mude para o mundo real e as coisas ficam um pouco mais confusas. Por exemplo, a função getSess(String tid, String aid)seria perfeitamente compreensível para um engenheiro de transporte que entendeu os sistemas DWDM, mas pode representar um desafio para o novo programador que acabou de colocar o projeto. Comentários bem colocados podem ajudar a facilitar a transição para a compreensão do código em tempo hábil.

2. Os programadores solicitados a manter o código geralmente não são tão habilidosos quanto os arquitetos originais do código. O programador original pode ter habilidade suficiente para escrever um algoritmo rápido, sucinto e eficiente para realizar uma tarefa específica. Mas o programador encarregado de manter esse código pode ter dificuldade em entender o que está acontecendo. Comentários bem colocados podem ajudar a facilitar a transição para a compreensão do código em tempo hábil.

3. Quantas vezes você escreveu um pouco de código que mais tarde se esforçou para entender por que fez isso ou mesmo o que estava tentando alcançar? Todos fazemos isso de tempos em tempos. Resolver um problema e produzir uma solução fácil de seguir para um problema costumam ser duas mentalidades diferentes. A menos que você seja a pessoa que pode escrever um código perfeitamente, muitas vezes você comete muitos erros no seu código à medida que avança. Talvez você também não consiga voltar a esse pedaço de código por um tempo. Comentários bem colocados podem ajudar a facilitar a transição para a compreensão do código em tempo hábil.

4. Situações únicas requerem explicação. Por exemplo, um programador pode se perguntar por que uma pausa de 100ms foi inserida em um pouco de código que se comunica com um dispositivo DWDM. Informar o próximo programador de que é necessária uma pausa porque o dispositivo é lento na captação e pode perder o comando seria uma informação valiosa. Comentários bem colocados podem ajudar a facilitar a transição para a compreensão do código em tempo hábil.

Um código de "auto-documentação" bem escrito, é uma alegria encontrar. Um código de "auto-documentação" bem escrito, com comentários informativos bem colocados, é uma dádiva de Deus e um achado muito raro.

Apenas para apresentar argumentos de cada lado da pergunta inicial:

Sim, o código é auto-documentado. As variáveis, métodos e nomes de classes podem ser criados para facilitar a leitura e a compreensão, de modo que essa seja uma forma de auto-documentação. Pode haver algo no estilo do código que forneça a documentação XML no final, que é considerado procedimento padrão. Em outras palavras, faz parte do trabalho do desenvolvedor fornecer documentação que possa ser misturada ao código.

Não, o código não é auto-documentado. As decisões de negócios tomadas, as escolhas de design feitas e outros fatores não aparecerão nas linhas de código e devem ser anotadas fora da base de código. Portanto, a documentação externa é necessária e estes são exemplos.

Ponto de perguntar: Você daria uma resposta parcial reconhecendo as limitações de uma resposta ou se apoiaria cegamente no lado que acredita ser a melhor prática? Quanta convicção você tem em sua resposta se for sim ou não? Pode ser vista como uma pergunta estressante, criada para provocar alguém que possa responder: "Qual é a ...? Essa é a pergunta mais idiota que você poderia me fazer. Recuso-me a responder com o argumento de que isso ofende minha inteligência além da crença! " como uma resposta bastante arrogante e pomposa que eu poderia imaginar algumas pessoas dando uma resposta com esse tom.

Obviamente, ele era um programador alfabetizado no estilo de Knuth. Para um discípulo de LP, o código deve ser auto-documentado para ser válido. Portanto, a única resposta possível é "sim".

O problema aqui é que não existem muitas linguagens de programação alfabetizadas e nenhuma que eu conheça em uso comercial generalizado. Portanto, teria que ser uma posição de nicho em algum lugar.

Eu acho que o que o entrevistador poderia estar procurando é: "Como você escreve código de auto-documentação?" com um implícito "Qual é a sua atitude em relação à documentação?"

Fui a uma palestra realmente inspiradora de um cara chamado Robert C Martin, onde ele falou sobre o capítulo 'métodos de escrita' de seu livro Clean Code.

Ele obviamente estava apresentando um pouco da posição de um purista, mas aceitei o conselho dele de que quando você corta seu código em pequenos métodos reutilizáveis ​​e usa truques simples como:

• Mantendo todas as instruções dentro de um método no mesmo nível de abstração
• Puxando o conteúdo da condição de fluxo de controle ou blocos de loop em chamadas de método
• Quando você passa os mesmos parâmetros em vários métodos de uma classe, separando uma nova classe
• E truques simples como substituir expressões booleanas enigmáticas por chamadas de método
• etc ...

Você acaba com um código legível e um pouco auto-documentável (desde que você se esforce em nomes concisos, mas descritivos), que é mais fácil de entender e manter.

Eu achei essas coisas realmente úteis, mas requer um conhecimento dos padrões de design para fazer bem e você definitivamente precisa complementar a abordagem com documentação de classe e método de alto nível.

Normalmente, o código de auto-documentação refere-se à prática de usar uma convenção de nomenclatura para variáveis, funções, etc., de modo que o objetivo do código seja evidente. Portanto, nenhum código por si só não é auto-documentado. Não entendo a que você se refere no terceiro parágrafo. Isso parece não ter nada a ver com o código de auto-documentação.

Jack Reeves argumentou convincentemente que o código é design . Para muitos, o código real é o único "documento" que informa o que o sistema faz. Tudo o resto decai como um sistema ativo tende a se afastar cada vez mais do sistema projetado. Mesmo que você gere um documento a partir do código (como muitas ferramentas UML podem fazer hoje em dia), ainda é apenas uma documentação precisa do sistema naquele momento .

Então, sim, o código é auto-documentado. Quão bem documentada é outra questão no todo.

À medida que me tornei mais experiente, aprendi que a resposta real é que o código mais o ambiente do leitor determina o nível de auto-documentação.

Para minimizar a variação entre o ambiente do leitor e o ambiente do escritor, adicionamos comentários. Quanto mais comentários são necessários, geralmente menos experiente é o escritor. Existe um ensaio maravilhoso descrevendo esse aspecto do desenvolvimento de software, mas não me lembro de quem o escreveu ou de onde o encontrei.

Eu sei que a resposta que a maioria das pessoas espera que essa pergunta seja "não", mas vou dizer que sim. Se me perguntassem isso em uma entrevista de emprego, ainda diria que sim.

Já trabalhei em vários projetos diferentes com código aberto e fechado. Eles variaram na documentação, desde comentários simples deixados como anotações do programador até documentações completas da API. Embora a documentação da API possa ser excelente, sempre cheguei a uma situação em que a documentação em linguagem escrita era insuficiente para determinar o comportamento real do código. Acabei analisando o código-fonte, fazendo engenharia reversa nos aplicativos ou importunando os desenvolvedores com acesso ao código-fonte para analisar o código-fonte e especificar mais.

Para mim, o código é a documentação definitiva. Não importa o quanto você escreva em palavras o que um programa fará, o comportamento exato é definido pelo código.

Concordo que, ao escrever o código, você deve tentar torná-lo o mais auto-descrito possível. No entanto, como outros já mencionaram, é quase impossível em um programa complexo descrever completamente tudo o que o código está fazendo. Não sou contra comentários; na verdade, acho que com bons comentários pode ser mais fácil ler o código, mesmo que o código possa se explicar sem que os comentários sejam em inglês ou em algum idioma falado seja quase sempre mais fácil.

Eu descobri que a documentação mais útil quase nunca é comentários. A maioria dos projetos em que tenho trabalhado recentemente inclui wiki, que inclui todas as partes diferentes, como elas se conectam. Tento explicar o que estava em minha mente quando escrevia o código para que outras pessoas não quebrassem o código porque não entenderam o porquê. Também pode ajudar alguém a refatorar o código com mais confiança. Muitas vezes, sinto-me hesitante em refatorar o código porque nunca sei o que ele pode quebrar e não há explicação. Mesmo que você seja a única pessoa trabalhando em um projeto que garanto em um ou dois anos, você esquecerá por que fez algo, mesmo que seja o mais belo código, você ainda pode esquecer por que está lá.

Claro, se você tiver tempo ilimitado. Passei mais de 25 anos documentando código para outros desenvolvedores. Minha posição sempre foi a de que eu tento explicar algo para que outro desenvolvedor possa entender isso em 5 minutos, quando eles podem simplesmente examinar o código e descobrir em meia hora. Se eu salvar todos os que olham para esse método em 25 minutos, então concluí meu trabalho.

Eu acho que o diagrama de classes sempre deve ser usado para documentar o código. Eu não acho que se você olhar diretamente para o código, poderá ver a arquitetura completa. Concordo que, se você mesmo escreveu o código ou trabalhou nele por um longo período de tempo, pode entender, mas cada vez que uma nova demanda surge, cada vez que você precisa olhar para o código e procurar onde adicionar esse novo código.

O que fazemos em nossa empresa é ter visualizações de diagramas de classes de nosso projeto. Realmente não gastamos tempo modelando, mas apenas usamos o diagrama de classes para visualizar o código após uma engenharia reversa. Se o código for alterado, existe um mecanismo de mesclagem e meus diagramas de classes são sempre atualizados.

O que é fantástico é poder adicionar comentários, restrições no diagrama, além do java doc. Revertemos o projeto e, em seguida, criamos um modelo e, finalmente, extraímos as visualizações do modelo exibido como diagramas de classe UML. Não codifico nesse estágio, mas obtenho uma cópia azul da arquitetura de código e trabalho nela para criar ou estender minha arquitetura atual. Se eu gostar, pressiono um botão e meu código existente é mesclado com meus diagramas. Quero dizer mesclar e certamente não geração de código completo. Somente o delta entre o código existente e meus diagramas é gravado, não o código completo toda vez.

Estou estudando há muitos anos, tenho mestrado e ainda codigo, mas não quero ser apenas um escritor de java e gostaria de usar meu cérebro um pouco mais. As visualizações UML fornecem o que eu preciso para pensar sobre minha arquitetura, comunicar-me com os outros membros da equipe e criar uma arquitetura melhor sem usar o desenvolvimento orientado a modelos, mas apenas o delta entre o código escrito manualmente existente e criar graficamente diagramas de classes. Eu crio minha arquitetura no nível do código, depois a inverto e olho para o modelo. Crio visualizações e tento melhorar minha arquitetura diretamente no código, depois inverto novamente e vejo o que é feito, etc ... É uma iteração permanente, sem geração de código orientada a modelo, mas com sincronização ao vivo ou mesclagem entre código e UML. O que eu gosto é que o código conduz a UML e certamente não o contrário.