Comentários aninhados

No tutorial de execução de código Lua falei sobre a possibilidade de incluir comentários em arquivos-fonte, isto é, conteúdo que não afetará a execução do código, mas que é útil para o programador ter uma melhor compreensão do código.

Um aspecto que não explorei no tutorial, mas que pode ser de grande utilidade em alguns casos é o fato de que podemos criar comentários de bloco aninhados, isto é, comentários dentro de comentários. Vejamos um exemplo:

--[[
    Este é um comentário de bloco mais externo
    --[-[
        E este é outro comentário de bloco
        mais interno. Note que ele possui um hífen
        a mais entre os sinais de colchetes para
        diferenciar do bloco externo.
    --]-]
--]]

Veja que adicionando um hífen entre os colchetes, isso significa que o comentário está em um nível diferente do bloco externo. Eu poderia adicionar mais hífens para denotar que são ainda outros blocos de comentário, em níveis diferentes.

Agora, você talvez esteja se perguntando, “qual seria a serventia de comentários aninhados, se no fim tudo são comentários”? Realmente, não serve muito se você não precisar mexer nos comentários. Mas será útil, se vez ou outra precisar descomentar o bloco mais externo.

Vejamos um cenário mais útil:

--[[
    i = 3
    --[-[
        Não estou certo se quero que i seja igual a 3,
        então por enquanto essa atribuição está dentro
        de um comentário (no bloco mais externo).
    --]-]
--]]

i = i or 5 -- se i não possui valor, será 5
print(i) --> 5

Muito bem, nesse exemplo, temos um comando de atribuição dentro do bloco mais externo. Por enquanto ele não surte efeito, mas podemos mudar de ideia no futuro.

Lembra do truque de desativação de comentários de bloco, adicionando um hífen extra na abertura? Vamos utilizá-lo aqui:

---[[
    i = 3
    --[-[
        ...
    --]-]
--]]

i = i or 5 -- se i não possui valor, será 5
           -- (mas agora possui, 3)
print(i) --> 3

Feito isso, o bloco de comentário externo foi desativado, e portanto a atribuição i = 3 agora surte efeito. Ao mesmo tempo, isso não afeta o bloco de comentário interno, que continua sendo um comentário de bloco válido.

É claro que para uma única linha eu poderia ter apenas usado um comentário de linha para a atribuição. Porém quando queremos ativar/desativar todo um conjunto de comandos, essa construção passa a ter mais utilidade.