Primeiro de tudo, nesta pergunta, eu gostaria de ficar longe da polêmica sobre se o comentário do código fonte é bom ou ruim. Estou apenas tentando entender mais claramente o que as pessoas querem dizer quando falam sobre comentários que dizem por que, o que ou como.
Muitas vezes, vemos diretrizes como "Os comentários devem informar POR QUE; o próprio código deve informar COMO". É fácil concordar com a afirmação em um nível abstrato. No entanto, as pessoas geralmente descartam isso como um dogma e saem da sala sem maiores explicações. Eu já vi isso usado em tantos lugares e contextos diferentes, que parece que as pessoas podem concordar com o slogan, mas parecem estar falando inteiramente de coisas diferentes.
Então, voltando à pergunta: se os comentários devem lhe dizer POR QUE, do que estamos falando? É por esse motivo que esse pedaço de código existe em primeiro lugar? É isso que esse código de peça deve estar fazendo? Eu realmente apreciaria se alguém pudesse dar uma explicação clara e depois adicionar alguns bons exemplos (exemplos ruins não são realmente necessários, mas ficaram à vontade para adicioná-los para contraste).
Há muitas perguntas sobre se os comentários são bons ou ruins, mas ninguém aborda a questão específica de quais são bons exemplos de comentários que dizem POR QUE.
fonte
There are many questions on whether comments are good or bad, but no one that addresses the specific question of what are good examples of comments that tell you WHY.
Se todos fornecerem um exemplo válido, todas serão respostas corretas. O formato deste site é facilitar um processo de perguntas e respostas em que nem todas as respostas são criadas da mesma forma.Respostas:
O exemplo mais comum e mais distinto são os comentários sobre várias soluções alternativas. Por exemplo, este:
Você certamente encontrará mais exemplos nas fontes Git e Linux; ambos os projetos tentam seguir esta regra.
Também recomendo seguir essa regra ainda mais estritamente com os logs de confirmação . Para comentários de código, pode ser que você corrija o código, mas esqueça de atualizar o comentário. Com a quantidade de código no projeto usual, é garantido que isso aconteça mais cedo ou mais tarde. Por outro lado, o log de confirmação está vinculado a uma alteração específica e pode ser recuperado usando a funcionalidade "anotar" / "culpar" do sistema de controle de versão. Novamente, o Git e o Linux têm alguns bons exemplos.
Veja, por exemplo, este commit . (não copiando aqui, é muito longo). Ele tem quatro parágrafos, ocupando quase toda a página (e um pouco mais do que a tela) descrevendo o que exatamente estava errado e por que estava errado, e continua e modifica todas as seis linhas pendentes. Eles usam comentários como esse para dois propósitos:
(note: demorei no máximo 10 minutos para navegar aleatoriamente no repositório git para apresentar esses dois exemplos, por isso seria fácil encontrar mais informações lá)
fonte
Um comentário que explica por que explica o raciocínio por trás do código - por exemplo:
Um comentário que explica como explica o que o código faz.
A diferença é que um mantenedor pode olhar para o primeiro e dizer: "Ah, então isso pode estar desatualizado!" No segundo caso, o referido mantenedor tem um comentário que não diz nada que o código em si não revela (assumindo bons nomes de variáveis).
Aqui está um exemplo da vida real de um comentário do porquê, de algum código do iOS em que trabalhei onde precisávamos obter um endereço de gateway (ou um palpite razoável). Eu poderia ter deixado os comentários que diziam coisas como "Inicializar o soquete de recebimento", mas isso apenas informava ao mantenedor (ou ao futuro) o que estava acontecendo, e não por que eu tinha que fazer esse estranho argumento para obter o endereço de gateway no diretório primeiro lugar.
fonte
Gostaria de começar minha resposta com uma citação feita por Jeff Atwood em sua postagem no blog Code Tells You How, Comments Tell You Why :
Ele também afirma que:
Concordo totalmente e, neste momento, devo acrescentar que, antes que eu possa começar a simplificar o código o mais simples possível, faço o código funcionar e, em seguida, começo a refatorar. Portanto, durante a primeira execução antes de refatorar, adicione por que os comentários ajudam muito.
Por exemplo, se você usar 3 loops aninhados com tabelas de hash bidimensionais para preencher uma tabela de dias úteis durante a análise de dados, é muito fácil perder o controle do que foi feito por alguém ou até por você mesmo se não for analisado por algumas semanas e refatorar repentinamente.
A parte superior é um exemplo de como 3 loops aninhados funcionariam antes da refatoração.
Também explicar algumas condições de ramificação pode ajudar a entender o código muito melhor com o que se estava pensando no processo:
Mesmo código simples e óbvio funciona bem com comentários. Apenas para tornar as coisas um pouco mais óbvias, mais claras ou fáceis de entender para os colegas e até para você na manutenção de software.
Claro que o xp declara ter um código que é autoexplicativo, mas um comentário de uma linha dói?
Também acho as seguintes regras deste blog muito úteis:
Qualquer pessoa que precise retornar ao seu próprio código ou a outra pessoa ou mesmo ao código legado sabe que pode ser uma dor de cabeça. Então, em vez de ser preguiçoso ou tentar ser um super-codificador em não comentar nada ou muito pouco, por que não fazer de si próprio ou de algum pobre coitado, que precisa manter seu código, uma vida futura muito mais fácil, seguindo as regras citadas.
Além disso, muitas decisões de programação feitas são questionadas durante as revisões e nem sempre é claro por que algumas partes foram escritas como eram, mesmo que algumas seções do código sejam vitais para o funcionamento de um programa devido a um erro grave encontrado durante o uso de códigos durante anos. . Portanto, para não aborrecer todos vocês completamente com um tl; dr perto com uma última citação de acmqueue :
fonte
int directionCode = (x > oldX) ? DIRECTIONCODE_RIGHT : (x > oldX) ? DIRECTIONCODE_LEFT : DIRECTIONCODE_NONE;
esteja com erro. Certamente deveria ser... (x < oldX) ? DIRECTIONCODE_LEFT : DIRECTIONCODE_NONE;
. Boas ideias para comentários - código incorreto.Eu tendem a reduzir os comentários para as referências em que uma determinada funcionalidade / código é explicada mais detalhadamente ou para explicar por que uma certa maneira de programação é escolhida.
Considerando que outros programadores com habilidades semelhantes usam ou leem seu código, é importante comentar se você usa uma maneira diferente do esperado de conseguir algo. Então você pode explicar em um comentário por que você escolhe esse caminho.
Por exemplo, se você pode usar dois sensores diferentes em um dispositivo Android e um deles não atender às suas necessidades, você pode explicar no comentário por que escolheu o outro.
Portanto, o "porquê" deve fundamentar suas escolhas.
fonte
Os comentários devem informar o que o código não faz, não necessariamente delineado por POR QUÊ , COMO ou O QUÊ . Se você tem bons nomes e possui funções bem delineadas, é bem possível que o código possa lhe dizer exatamente o que está acontecendo. Por exemplo:
Este código realmente não precisa de comentários. Os nomes de função e tipo facilitam o entendimento.
Às vezes, no entanto, pode ser difícil ou impossível criar realmente um código fluente como o acima. Por exemplo, o próximo trecho de código é para encontrar um ponto estatisticamente aleatório em uma esfera. A matemática é bastante opaca, portanto, um comentário com um link para a explicação é ajudar a dizer como funciona. Isto pode ser envolto em uma função para contar QUE ele faz sem a necessidade de um comentário se necessário mais de uma vez, caso contrário, o título do link também ajuda nesse departamento.
Outro exemplo de quando os comentários dizem o que o código não explica é para explicar uma decisão. No próximo exemplo, o código não bloqueia uma variável local não thread dentro de um trecho de código encadeado. Há uma razão para isso e o comentário explica POR QUE . Sem o comentário, pode ser considerado um bug, ou simplesmente nem ser notado.
Talvez possa ser melhorado dizer por que o objeto aleatório não é criado dentro do loop paralelo em primeiro lugar. Se não houver razão, isso também pode fazer com que alguém apareça e perceba que toda a idéia é estúpida e é um bom lugar para refatoração.
fonte
WriteText
e não//
?Pode ser útil reconhecer diferentes tipos de "porquê" - principalmente:
Razões pelas quais o código que parece excessivamente complexo não funcionaria se simplificado (por exemplo, uma digitação aparentemente supérflua pode ser necessária para garantir que o código funcione em alguns casos de canto).
Motivos pelos quais alguma operação simples específica que parece perigosa é realmente segura (por exemplo, "Nossa rotina de busca de dados reportará um item fictício do item após o último como sendo menor do que qualquer outra coisa, e o item depois como sendo maior; qualquer item que deva classificar antes de outro, em uma sequência ascendente ou descendente consistente, terá pelo menos mais um item (possivelmente falso) seguindo-o ").
Em muitos casos, um comentário do segundo tipo em uma parte do código pode "corresponder" a um comentário do primeiro tipo em outra (por exemplo, "Embora pareça que essa sequência de operações possa ser simplificada, a rotina Fitz se baseia em o Wongle não será Woozled até depois que o Bandersnatch tenha sido tocado. ")
fonte
Não se esqueça, se você está escrevendo um programa, não está apenas digitando coisas aleatoriamente, mas sim porque tem um modelo do que deseja , seja em um documento formal ou apenas na sua cabeça. Coisas na sua cabeça são tão reais quanto software / dados em um computador (e com a mesma probabilidade de conter bugs).
Alguém que lê o seu código pode não ter esse modelo na cabeça; portanto, os comentários podem servir para dizer qual era o modelo e como o código está relacionado a ele. Eu acho que é isso que significa "por que". Certamente, é bom tornar o código em si o mais auto-explicativo possível, mas isso nem sempre é bom o suficiente. Exemplo:
Além disso, o modelo muda com o tempo e essas alterações precisam ser transferidas para o código. Portanto, os comentários precisam não apenas dizer "por que" algo está no código, mas também tão importante quanto alterá-lo em resposta a alterações antecipadas do modelo. Exemplo:
Eu acho que esse propósito para comentários às vezes é negligenciado.
fonte
Nem todos os meus comentários são do tipo 'por que', mas muitos são.
Estes são exemplos de um arquivo de origem (Delphi):
Observe que (meu) por que os comentários geralmente precedem o código que o fará (portanto, termina com dois pontos).
Eu tenho alguns comentários explicando apenas o que está acontecendo, por exemplo, quando um processo tem muitas etapas que possuem um agrupamento lógico (e o código não é refatorado para mostrar isso automaticamente), comentarei como:
fonte
Entendo o porquê como a razão pela qual você faz algo de uma maneira possivelmente estranha ou talvez ilógica, devido às circunstâncias que exigem que isso seja feito. O HOW pode ser visto no próprio código, por mais estranho que seja, mesmo que o código não faça "sentido". O QUE é provavelmente melhor dito no início da documentação de classe / função. Isso deixa você adicionando o PORQUÊ , onde você explica tudo o que não está incluído no COMO e O QUE, e as maneiras peculiares que você precisa seguir devido a razões fora de seu controle.
Claro que nem sempre é o caso, fora da terra dos unicórnios e do arco-íris ...
QUÃO:
O QUE:
PORQUE:
fonte
critters.dance()
, o comentário apenas repete o óbvio, e "Não conseguimos fazer com que funcionasse de qualquer outra maneira que tentamos" é completamente inútil. Além disso, dizer "chamaremos o método para cada objeto" está repetindo o que o código diz claramente.Eu aprendi a escrever SEMPRE comentários em arquivos de cabeçalho C ++ (já que nem sempre é claro o que uma função faz, mesmo que o nome dê uma boa dica), especialmente se você passar uma API para outros desenvolvedores ou usar uma ferramenta para autodoc como doxygen.
Então, para mim, um comentário típico parece algo como
A única vez em que usei POR QUE os comentários são coisas difíceis de entender e, às vezes, até para o programador, como "NÃO TOQUE NESTE! Porque ..." ou "O PROGRAMA VAI COLOCAR SE A LINHA É EXCLUÍDA ..."
Soluções alternativas, hacks e comportamento estranho se qualificam para os critérios WHY aos meus olhos ...
Um exemplo muito bom e até hilário é essa "solução alternativa" para algum código confuso escrito por uma pessoa chamada Richard, alguém o envolveu e explicou por que nos comentários ... https://stackoverflow.com/a/184673/979785
Infelizmente, existem algumas vezes em que você é forçado a quebrar a merda porque não pode tocar no original, ou porque "sempre foi assim" ou você não tem acesso ou ... bem, você não tem tempo para consertar o original para a finalidade realmente não se qualifica para a sobrecarga.
fonte
documentation
tag é lamentável, mas ainda não se aplica à pergunta).O código deve especificar o plano de execução. Dessa forma, o seguidor do programa (ou o compilador) pode descobrir o que fazer e como fazê-lo. O que é dividido em etapas que o seguidor do programa pode seguir. Os passos primitivos são o como.
A intenção do codificador é outra questão. Em um código simples, claro e direto, a intenção é óbvia. Qualquer leitor humano razoavelmente proficiente chegará à intenção de um bloco de código, apenas lendo o código. A maioria dos códigos deve ser assim.
Ocasionalmente, a relação entre intenção e plano é obscura. O código revela o quê e como, mas não o porquê. É quando os comentários que revelam a intenção valem a pena. A intenção do programador é o porquê.
fonte
Ter esse problema no momento percorrendo procedimentos armazenados e visualizações em um modelo de dados complexo e um tanto complicado.
Criamos (numerosas) seleções como "Caso em que x.account não é nulo e x.address in (selecione o endereço do fedex) e x.account else y.ccount end" e a produtividade é esperada, embora não haja tempo em tudo para ler todo o código fonte. E esse exemplo meio que faz sentido, mas ainda é inescrutável.
Os comentários explicando por que, se no fedex, x e se não, y - lança luz sobre todo o sistema e, quando lemos o suficiente, começamos a obtê-lo. E isso é simplificado e existem centenas ou milhares de declarações semelhantes. Meu coração brilha calorosamente em relação a quem foi o tipo dev de 2007 que colocou aqueles por que.
Então sim, modelos de dados complexos e complicados, veiws peludos e procedimento armazenado com vários caminhos com nome válido, por favor, pelo amor de D'us, diga-nos o porquê.
fonte
Acabei de escrever este comentário; é um exemplo concreto de explicar por que uma linha de código é o que é e, em particular, por que eu a mudei.
O método examina os dados armazenados e avalia se eles estão completos até os dias atuais, por um lado, e até a data de início do outro lado.
Como você provavelmente pode adivinhar, o operador maior que tinha sido maior ou igual. O comentário explica por que o valor antigo faz sentido e por que o novo valor é melhor. Se alguém olhar para isso no futuro, verá que o uso de ">" não é uma supervisão, mas uma otimização. Eles podem alterá-lo ou deixá-lo, com base na necessidade naquele momento.
fonte