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?

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.

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) {
  ...
}

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.

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.

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.

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

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

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

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();
}