Sempre que estou escrevendo uma construção típica de se-outro-em qualquer idioma, pergunto-me qual seria a melhor maneira (em termos de legibilidade e visão geral) para adicionar comentários a ela. Especialmente ao comentar a cláusula else, os comentários sempre parecem fora de lugar para mim. Digamos que temos uma construção como esta (exemplos estão escritos em PHP):
if ($big == true) {
bigMagic();
} else {
smallMagic()
}
Eu poderia comentar assim:
// check, what kind of magic should happen
if ($big == true) {
// do some big magic stuff
bigMagic();
} else {
// small magic is enough
smallMagic()
}
ou
// check, what kind of magic should happen
// do some big magic stuff
if ($big == true) {
bigMagic();
}
// small magic is enough
else {
smallMagic()
}
ou
// check, what kind of magic should happen
// if: do some big magic stuff
// else: small magic is enough
if ($big == true) {
bigMagic();
} else {
smallMagic()
}
Quais são seus exemplos de melhores práticas para comentar isso?
else { // for future reader: sorry, at the moment of writing this I did not have time and skills to come up with a better way to express my logic
Respostas:
Eu prefiro:
ou:
Parece um pouco tolo escrever um comentário explicando o que sua condição verifica, a menos que o código não a indique claramente. Mesmo assim, é melhor reescrever o código para torná-lo o mais claro possível. O mesmo vale para os corpos dos blocos condicionais - se você puder fazer o motivo de fazer algo óbvio, faça isso em vez de comentar.
Não subscrevo a filosofia "nunca escrever comentários", mas acredito em evitar comentários que digam o que o código deveria estar dizendo. Se você escrever um comentário como "verifique que tipo de mágica deve acontecer" quando o código poderia dizer
if ($magic == big) {...
, os leitores deixarão de ler seus comentários muito rapidamente. Usar menos comentários mais significativos dá a cada um de seus comentários mais valor e é muito mais provável que os leitores prestem atenção naqueles que você escreve.A escolha de nomes significativos para suas variáveis e funções é importante. Um nome bem escolhido pode eliminar a necessidade de comentários explicativos em todo o seu código. No seu exemplo,
$magic
ou talvez$kindOfMagic
pareça um nome melhor do$big
que, de acordo com o seu exemplo, é o "tipo de mágica" que está sendo testado, não a "grandeza" de alguma coisa.Diga o máximo que puder no código. Guarde a prosa para os casos que exigem mais explicações do que você pode razoavelmente escrever no código.
fonte
Tente nomes de variáveis explicativos
Os comentários podem ser ótimos, mas, quando possível, torne o código auto-documentado. Uma maneira de fazer isso é com nomes de variáveis explicativos. Por exemplo, em vez disso:
Eu preferiria uma variável nomeada:
fonte
is_potential_elvis_impersonator
. (IS / tem / etc prefixo para variável booleana ...)Apenas para concluir alguns comentários:
BTW: Eu recomendo este livro.
fonte
Os comentários não devem parafrasear o código, mas explicam coisas que não estão no código (imagem maior, por que, por que uma alternativa não foi escolhida ...) E o seu exemplo de comentário é exatamente isso: parafrasear o código.
Às vezes, você pode sentir que é necessária uma paráfrase no início da
else
ramificação, mas isso geralmente é um sinal de que suathen
ramificação é muito grande.fonte
No seu exemplo específico, os comentários provavelmente não são necessários. Como Caleb mencionou , se o código for claramente escrito e as variáveis tiverem nomes semânticos, se as instruções tiverem menos probabilidade de comentar.
Compare seu snippet com este:
Nesse caso, você definitivamente gostaria de usar comentários para descrever o que x, func1 e func2 representam (e dar um tapa na pessoa que nomeou as coisas por esse esquema, especialmente se fosse você). Você não pode nem dizer se
$x
deveria ser um booleano. Mas esse também é um caso em que você não precisa necessariamente de comentários, se conseguir refatorar e renomear.Em geral, eu gosto de escrever comentários para blocos lógicos que descrevem coisas que o código não pode por si só. Uma linha única a cada ~ 10-20 linhas que descreve o que as seguintes linhas realizam em um nível mais alto de abstração (por exemplo,
// Make the right amount of magic happen
por exemplo) ajudará a mantê-lo orientado e fornecerá a um novo revisor informações sobre o que você está fazendo e quando .Na verdade, muitas vezes escrevo essas linhas de uma linha antes de começar a escrever o código, para não perder a noção do fluxo que o segmento deveria ter.
Por fim, se você realmente prefere (ou há um mandato que exige) comentar cláusulas em um bloco if independentemente da legibilidade do código, recomendo:
Eu acho que é o mais limpo, porque o comentário está alinhado com o código ao qual pertence. Um comentário descrevendo o que o código faz deve ser o mais próximo possível do comentário que ele descreve.
fonte
Eu mantenho meus suportes alinhados e coloco logo após o suporte.
[Condition] -> [pseudo-code]
Em outro caso, tecnicamente significa que todas as outras condições falharam, então geralmente uso parênteses.
([Condition]) -> [pseudo-code]
Nota: isto é para C #.
fonte
Eu tento usar comentários dentro do bloco dizendo o que esse bloco faz (sua primeira amostra).
Onde isso meio que quebra é quando se usa
elseif
. Eu uso o Basic para que não haja um bloco final explícito e, muitas vezes, tenha que comentar qual é a condição que está checando a linha acima (com uma quebra de linha, é claro) se for muito longa.fonte
Se todas as opções acima falharem, adicione um comentário descritivo muito pequeno antes da declaração if, para esclarecer sua intenção. Caso contrário, realmente não deveria haver necessidade de comentar nada.
fonte
Em C ++ ou C #, normalmente eu não comentava casos simples (quando está claro o que está acontecendo) e usava esse tipo de estilo para comentar a outra coisa final ...
fonte