O que é uma boa maneira de comentar se-else-cláusulas? [fechadas]

14

Sempre que estou escrevendo um típico if-else-construct em qualquer idioma, gostaria de saber qual seria a melhor maneira (em termos de legibilidade e visão geral) de adicionar comentários a ele. Especialmente ao comentar a cláusula else, os comentários sempre parecem fora do lugar para mim. Digamos que temos uma construção como essa (exemplos sã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 os exemplos de melhores práticas para comentar isso?

    
por acme 04.04.2012 / 12:25
fonte

9 respostas

34

Eu também 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 bobo escrever um comentário explicando o que sua condição verifica, a menos que o código não 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 a razão para fazer algo óbvio, faça isso em vez de comentar.

Eu não assino a filosofia "nunca escreva 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 pode dizer if ($magic == big) {... , os leitores vão parar de ler seus comentários muito rapidamente. Usar menos comentários mais significativos dá a cada um de seus comentários mais valor, e os leitores têm mais probabilidade de prestar 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 parece ser um nome melhor que $big , pois, de acordo com o seu exemplo, é o "tipo de mágica" que está sendo testado, não a "grandeza" de algo.

Diga o máximo que puder no código. Salve prosa para os casos que exigem mais explicações do que você pode razoavelmente escrever no código.

    
por 04.04.2012 / 12:39
fonte
11

Tente nomes de variáveis explicativas

Os comentários podem ser ótimos, mas, quando possível, tornam o código autodocumentado. Uma maneira de fazer isso é com nomes de variáveis explicativas. Por exemplo, em vez disso:

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

}

Eu prefiro uma variável nomeada:

is_potential_elvis_impersonator = user.has_sideburns && user.can_gyrate

if (is_potential_elvis_impersonator) {
  ...
}
    
por 04.04.2012 / 18:13
fonte
3

Apenas para completar alguns comentários:

The proper use of comments is to compensate for our failure to express ourself in code. Note that I used the word failure. I meant it. Comments are always failures. We must have them because we cannot always figure out how to express ourselves without them, but their use is not a cause for celebration. (Clean Code by Robert C. Martin)

BTW: Eu recomendo este livro.

    
por 04.04.2012 / 21:53
fonte
3

Os comentários não devem parafrasear o código, mas explicar coisas que não estão no código (por exemplo, por que uma alternativa não foi escolhida ...) E seus comentários de exemplo são apenas isso: paráfrase do código .

Às vezes, você pode sentir que uma paráfrase é necessária no início da ramificação else , mas isso geralmente é um sinal de que sua ramificação then é muito grande.

    
por 04.04.2012 / 15:40
fonte
2

No seu exemplo específico, os comentários provavelmente não são necessários. Como Caleb mencionou , se o código estiver claramente escrito e as variáveis tiverem nomes semânticos, se as declarações tiverem menor probabilidade de precisar de comentários .

Compare seu snippet com isso:

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

Nesse caso, você definitivamente desejaria usar comentários para descrever o que x, func1 e func2 representam (e tapa a pessoa que nomeou as coisas por esse esquema, especialmente se fosse você). Você não pode sequer dizer se $x deve ser um booleano. Mas este também é um caso em que você não precisa necessariamente de comentários, se é capaz de refatorar e renomear.

Em geral, gosto de escrever comentários para blocos lógicos que descrevem coisas que o código não consegue por si próprio. Um one-liner de cada ~ 10-20 linhas que descreve o seguinte conjunto de linhas em um nível mais alto de abstração (por exemplo, // Make the right amount of magic happen para o seu exemplo) ajudará a mantê-lo orientado e dará uma nova visão ao usuário fazendo e quando.

Na verdade, eu geralmente escrevo esses versos em antes começo a escrever código, para não perder o controle do fluxo que o segmento deve ter.

Por fim, se você realmente preferir (ou há um mandato que requeira) cláusulas de comentários 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 sinto que é o mais limpo, porque o comentário está alinhado com o código ao qual pertence. Um comentário descrevendo qual código deve ser o mais próximo possível do comentário que ele descreve.

    
por 04.04.2012 / 15:33
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 outra coisa, tecnicamente significa que todas as outras condições falharam, então eu geralmente uso parênteses.

([Condition]) -> [pseudo-code]

Nota: isto é para C #.

    
por 04.04.2012 / 17:35
fonte
1

Eu tento e uso comentários dentro do bloco dizendo o que esse bloco faz (sua primeira amostra).

Onde esse tipo de quebra é quando usamos elseif . Eu uso o Basic, então não há bloco final explícito e muitas vezes tenho que comentar o que a condição está verificando, o que vai na linha acima (com uma quebra de linha, é claro) se for muito longo.

'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
    
por 04.04.2012 / 12:55
fonte
1
  • Mantenha seus bloqueios condicionais muito curtos.
  • Chame um método com um nome descritivo legal se parecer que seu código condicional será mais do que uma simples linha ou duas.
  • Use nomes descritivos para suas variáveis.
  • Certifique-se de que a instrução condicional esteja 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 todos os itens acima falharem, adicione um comentário descritivo muito pequeno antes da instrução if para esclarecer sua intenção. Caso contrário, não deveria haver necessidade de comentar nada.

    
por 05.04.2012 / 10:33
fonte
0

Em C ++ ou C # eu normalmente não comentaria casos simples (quando está claro o que está acontecendo), e usaria esse tipo de estilo para comentar o último ...

if (pattern == AAA)
{
  DoSomethingAAA();
}
else if (pattern == BBB)
{
  DoSomethingBBB();
}
else // if (pattern == CCC)
{
  DoSomethingCCC();
}
    
por 04.04.2012 / 15:08
fonte

Tags