Qual é uma boa maneira de comentar cláusulas if-else? [fechadas]

15

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?

acme
fonte
8
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
mosquito
1
Por que Bigger é melhor / preferível / diferente? Veja, eu não sei.
Jeffo
Este é um assunto a ser questionado ou discutido? Mesmo que a pergunta seja bem-intencionada, esses são os fatores que desencadeiam a guerra.
Independente
1
Acho interessante que muitas pessoas achem que essa pergunta vale a pena ser respondida, mas não vale a pena votar. Embora eu esteja interessado nas respostas (a minha é o único +1), a pergunta parece ser um exemplo por excelência de um problema de troca de bicicletas.
Canisrufus
1
@canisrufus Só parece assim para você, porque os votos negativos compensam os votos positivos. Neste momento, existem 6 votos positivos e negativos para uma rede +2.
Caleb

Respostas:

34

Eu prefiro:

if ($magic == big) {
    bigMagic();
}
else {
    smallMagic();
}

ou:

if ($magic == big) {
    // big magic requires a big surprise, so I'm telling you about it here
    surprisingThing();
}
else {
    // give a magical feeling even if $magic is noMagicAtAll
    smallMagic();
}

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, $magicou talvez $kindOfMagicpareça um nome melhor do $bigque, 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.

Caleb
fonte
13
+1 não exagere comentários, código claro não requer comentários
aberração catraca
3
@ratchetfreak Parece que estamos de acordo, mas os comentários geralmente são necessários para tornar o código claro. Fornecer contexto histórico, explicar comportamentos surpreendentes ou resolver ambigüidades é melhor feito com comentários.
Caleb
1
Bom ponto, Caleb. É verdade que o código deve algum tipo de auto-comentário, contanto que seja possível.
Acme #
7
Bons comentários não explicam o que - "verifique, que tipo de mágica deve acontecer" - eles explicam o porquê, ou seja, "Os usuários podem selecionar o tipo de mágica para executar" ou "O serviço preencherá grandes magias se estiverem disponível, então devemos verificar o tipo "ou o que for. Não importa quão boa seja sua codificação, os porquês são desconhecidos para aqueles que não estão familiarizados com as regras de negócios.
Bruno Brant
1
O problema é que é mais fácil escrever código difícil de ler e não comentar. Também é mais fácil escrever código difícil de ler, mas comente-o bem do que escrever consistentemente um código tão bom que não precise de comentários.
asfallows
11

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:

if (user.has_sideburns && user.can_gyrate) {
  // This user is a potential Elvis impersonator

}

Eu preferiria uma variável nomeada:

is_potential_elvis_impersonator = user.has_sideburns && user.can_gyrate

if (is_potential_elvis_impersonator) {
  ...
}
Nathan Long
fonte
2
I ir um passo além e uso: is_potential_elvis_impersonator. (IS / tem / etc prefixo para variável booleana ...)
Jake Berger
@berger - eu gosto. Edição de resposta em conformidade.
Nathan Long
3

Apenas para concluir alguns comentários:

O uso adequado dos comentários é para compensar nossa falha em nos expressar em código. Note que eu usei a palavra falha. Eu quis dizer isso. Os comentários são sempre falhas. Devemos tê-los, porque nem sempre podemos descobrir como nos expressar sem eles, mas o uso deles não é motivo de comemoração. ( Código Limpo de Robert C. Martin )

BTW: Eu recomendo este livro.

CSA
fonte
3

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 elseramificação, mas isso geralmente é um sinal de que sua thenramificação é muito grande.

AProgrammer
fonte
2

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:

if ($x) {
    func1();
} else {
    func2();
}

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 $xdeveria 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 happenpor 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:

// Broad description of block
if (something) {
    //Do this because something
    something();
} else {
    //Do this because !something
    somethingElse();
}

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.

asfallows
fonte
2
if (IsWeekDay(day))
{// weekday -> alarm at 7am
   ...
}
else if(day == DayOfWeek.Saturday)
{// saturday -> alarm at 11am
   ...
}
else
{// (sunday) -> no alarm
   ...
}

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 #.

Jake Berger
fonte
1

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.

'Check XYZ
If Condition1 then
  'We need to do T and S
  DoCodeFor1();

'Check ABC
ElseIf Condition1 then
  'This requires something else to be done
  DoCodeFor2()

Else
  'We have no other option than to...
  DoCodeFor3()

End If
Deanna
fonte
Sim, isso realmente funciona melhor quando você usa um idioma sem parênteses.
Acme #
1
  • Mantenha seus bloqueios condicionais muito curtos.
  • Chame um método com um bom nome descritivo se parecer que seu código condicional será mais do que uma simples linha ou duas.
  • Use bons nomes descritivos para suas variáveis.
  • Certifique-se de que a declaração condicional seja clara em seu significado e não ofuscada ou longa. Use um método se isso ajudar a manter as coisas limpas e legíveis.

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.

S.Robins
fonte
0

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

if (pattern == AAA)
{
  DoSomethingAAA();
}
else if (pattern == BBB)
{
  DoSomethingBBB();
}
else // if (pattern == CCC)
{
  DoSomethingCCC();
}
dodgy_coder
fonte
4
Ou melhor, "pattern.doSomething ()" e deixe o OO fazer seu trabalho.
Paul Tomblin