DEV Community: Davi Augusto

Comente o porquê, não o quê

Davi Augusto — Sat, 18 Jan 2025 15:47:37 +0000

Comentários podem ajudar você ou seus colegas a entenderem decisões cruciais por trás do design do código de um projeto. Porém, para que isso aconteça, é importante saber diferenciar quando e como comentar, de forma que os seus comentários não se transformem em informação desatualizada ou simplesmente redundante.

Tipos de comentários

Ao ler diferentes comentários em diferentes projetos, é possível notar que alguns "tipos" de comentários podem ser formados, com base no que eles informam e em como são feitos.

Comentários redundantes

Alguns comentários podem ser classificado como redundantes, ou triviais. Normalmente esses comentários repetem o que já é possível inferir pelos nomes das funções chamadas e nomes de variáveis.

// carrega configuração
cfg, err := config.Load()
if err != nil {
    return err
}

Esse tipo, apesar de desnecessário, tende a não causar um impacto negativo de grande magnitude. Isso, pois ele custa tanto ao autor do código, quanto ao leitor, pouco trabalho e esforço cognitivo. Dito esse, ainda se trata de comentários desnecessários e que não agregam valor.

Comentários explicativos

Esse tipo de comentário tende a variar em questão de complexidade. Em certos casos, ele pode explicar ações que desenvolvedores já acostumados com a linguagem em uso entendem facilmente, mas desenvolvedores mais novatos podem ainda não entender.

// Retorna o resultado da promise que resolver primeiro
const data = await Promise.race([mainServerPromise, secondaryServerPromise]);

Esse caso pode trazer algum valor, simplificando a leitura para alguns. Apesar disso, ele ainda polui o projeto de informação que eventualmente pode ser considerada redundante. No exemplo acima, um desenvolvedor que ainda não conheça Promise.race precisa pesquisar e aprender apenas uma vez para que o comentário não agregue mais valor. Além disso, é preciso definir em quantos casos esse comentário será usado. Se a função Promise.race for usada muitas vezes em um módulo, onde você coloca esse comentários e quantas vezes?

Assim, esse comentário também se torna indesejado, apesar de também causar um baixo esforço cognitivo.

Outra caso em que é possível ver comentários explicativos é como explicação de implementação de algoritmos, ou alguma lógica um pouco mais estruturada. Isso é mais comum em casos em que um CRUD clássico, normalmente relacionado apenas a implementações de regras simples, e integrações, precisa implementar alguma lógica mais estruturada.

// exemplo simplista desse caso.

func binarySearch(arr []int, target int) int {
    left, right := 0, len(arr)-1

    for left <= right {
        mid := left + (right-left)/2 // Calcula o índice do meio

        if arr[mid] == target {
            return mid
        }

        // Se target é maior, ignora a metade esquerda
        if arr[mid] < target {
            left = mid + 1
        } else {
            // Se target é menor, ignora a metade direita
            right = mid - 1
        }
    }

    // target não encontrado
    return -1
}

Esse caso tende a agregar mais valor. Além disso, ele serve pra ajudar o leitor a se situar durante a leitura. Por mais que ele seja capaz de identificar a lógica e as etapas envolvidas no algoritmo sem o auxílio de comentários, eles podem ajudar a distinguir visualmente as etapas dele com mais facilidade.

Comentários como documentação de API

Um tipo que tm se popularizado mais, com linguagens com Go e Rust, mas também presentes em linguagens mais antigas como JavaScript (JSDoc) e Java (JavaDoc), é o comentário de documentação de API.

Cada linguagem adota seu padrão de como esses comentários devem ser estruturados, mas eles possuem imenso valor, especialmente quando acoplados com algum gerador automático de documentação. O pkg.go.dev (Go) e crates.io (Rust) são exemplos fantásticos disso. Desenvolvedores de bibliotecas podem contar apenas com as funcionalidades da linguagem para ter uma documentação profunda de suas bibliotecas, sem precisar de desenvolver sites externos (mas alguns ainda optam por isso para terem mais controles sobre o fluxo de sua documentação).

Uma vantagem ainda maior dessa forma de documentação é ela estar próxima ao código. Atualizar a implementação e a documentação torna-se possível com um único commit.

// Exemplo da biblioteca padrão em Go

// Sort sorts a slice of any ordered type in ascending order.
// When sorting floating-point numbers, NaNs are ordered before other values.
func Sort[S ~[]E, E cmp.Ordered](x S) {
    n := len(x)
    pdqsortOrdered(x, 0, n, bits.Len(uint(n)))
}

Esse tipo de comentário está sujeito à redundância, especialmente com funções mais triviais em pacotes. Apesar disso, ainda é extremamente útil pois a ausência de ressalvas no comentário tranquiliza o leitor, enquanto a ausência de comentários pode não informar muito. Além disso, mesmo com informações redundantes, a presença deles padroniza a documentação da API.

Comentários de design

Dentre os mencionados, esse é o único tipo de comentário que é capaz de adicionar informação que não está contida no próprio código. Essa classe de comentários informa ao leitor a razão de uma implementação, podendo conter contextos técnicos e de negócio, deixando o leitor a par do porquê certa ação foi tomada. Esse tipo de contexto normalmente não se encontra no resto do código e, além de justificar a implementação, ajuda o leitor a entender melhor sobre as diretrizes e objetivos do código.

// Código do pacote http, na biblioteca padrão do Go
// fonte: https://cs.opensource.google/go/go/+/refs/tags/go1.23.5:src/net/http/client.go;l=717


// ...
if err != nil {
    // Special case for Go 1 compatibility: return both the response
    // and an error if the CheckRedirect function failed.
    // See https://golang.org/issue/3795
    // The resp.Body has already been closed.
    ue := uerr(err)
    ue.(*url.Error).URL = loc
    return resp, ue
}
//...

O exemplo acima descreve que erro é retornado junto à a resposta caso a função CheckRedirect falhe por motivos de compatibilidade, evitando quebrar códigos antigos que dependam desse comportamento. Além disso, inclui um link de uma issue relacionada, onde o leitor pode buscar ainda mais contexto por trás da escolha.

Esse tipo de comentário agrega muito valor, deixando o leitor a par das escolhas e até possíveis débitos técnicos. Ele adiciona um contexto valioso que, originalmente, apenas o autor tinha. Dessa forma, leitores futuros conseguem traçar uma forma de histórico, podendo entender problemas aos quais ele deve se atentar ao modificar o código, e tendo um norte para suas edições.

Comentários desatualizados

Tendo isso em vista, vale observar que todos esses tipos de comentários são passíveis de se tornarem desatualizados. Para qualquer tipo, isso pode gerar um trecho de código contra-produtivo, que desinforma o leitor. Dito isso, é algo que acontece mais facilmente com comentários que explicam o código, ao invés de comentários que explicam o porquê (comentários de design). Isso se dá pela própria natureza dos comentários. Aqueles que estão 100% atrelados ao código e apenas reforçam ideias que o próprio código já expressa estão fadados à necessidade de sempre mudarem com o código. Já os comentários de design, mesmo quando desatualizados (a implementação que eles justificavam foi alterada), ainda proveem contexto histórico, por mais que desnecessário.

Dessa forma, observa-se necessário dar atenção aos comentários como parte do processo de commits, e PRs. Sempre que algum trecho de código é alterado, é importante que seja dada atenção aos blocos de comentários relacionados a esse trecho. Isso, claro, é mais fácil quando os comentários são imediatos ao código a que se referem. Dê uma atenção aos comentários durante o seu próximo processo de code review :).

Conclusão

Como regra geral, é sempre interessante comentar o porquê do seu código, dando ao leitor contexto que você tinha durante a autoria do código. Evitar redundância em comentários deixa o seu código limpo e menos confuso, além de manter um fluxo mais legível.

Comentários, assim como programação em si, não seguem regras fixas. Há casos diferentes e sempre contexto a ser considerado, mas algumas diretrizes podem ser adotas para guiar a inserção de comentários.

E não caia no papo de que código bom não precisa de comentários.

Desvendando Subprocessos: Criando um Bot de Música com Go

Davi Augusto — Mon, 13 Jan 2025 17:19:37 +0000

Ao tentar criar um bot de música para o Discord em Go, aprendi um pouco mais sobre alguns conceitos:

Subprocessos
Áudio Opus
Formato Ogg

Vou ensinar o que aprendi nesse post. Ressalto que esse post é para fins educacionais e há formas mais simples de atingir o objetivo do bot de música. O intuito aqui é ensinar um pouco do que aprendi durante minha primeira tentativa.

Visão geral

Em alto nível, o bot vai funcionar com uma pipeline. Usaremos o yt-dlp para extrair o áudio do YouTube (o programa aceita várias fontes, mas aqui iremos focar no YouTube) e o ffmpeg para garantir um encoding padrão e consistente do áudio. Por fim, vamos precisar extrair frames Opus do áudio providenciado pelo ffmpeg para enviar ao Discord, mas isso será feito diretamente no código Go. Dado isso, certifique-se que ambos o yt-dlp e o ffmpeg estejam instalados para o funcionamento correto.

Baixando o áudio

O yt-dlp, por padrão, baixa vídeos por completo do YouTube. No nosso caso, queremos apenas o áudio. Isso pode ser atingido com a flag --extract-audio (um alias mais curto dessa flag é -x):

yt-dlp --extract-audio "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

Como podemos executar isso em código Go? É simples, usando o pacote exec da biblioteca padrão, conseguimos facilmente executar o mesmo comando. O pacote é responsável por configurar e iniciar subprocessos, que executam programas externos.

dlp := exec.Command("yt-dlp", "--extract-audio", "https://www.youtube.com/watch?v=dQw4w9WgXcQ")
dlp.Run()

Com esse trecho, iniciamos um subprocesso que executa o yt-dlp. O uso do método cmd.Run inicia o subprocesso, e espera sua finalização na goroutine atual.

É possível que o resultado do yt-dlp sendo chamado manualmente gere um arquivo .opus válido. Isso acontece porque o yt-dlp já chama o ffmpeg nesse caso. Isso não será útil para nós porque ao usar pipes (visto posteriormente), o áudio não é gerado nesse formato

Codificando o áudio

A documentação da API do Discord menciona que o áudio deve ser enviado no formato Opus a um sample rate de 48kHz e com dois canais (stereo). A biblioteca que iremos usar mais a frente, discordgo, lida com todos os outros detalhes técnicos do envio, como criptografia end-to-end e gerenciamento do estado. Dito isso, ainda cabe a nós o envio apropriado dos bytes de áudio.

Tendo isso em mente, procurei a ferramenta mais famosa para processamento multimídia, o ffmpeg. Podemos gerar um arquivo opus da seguinte forma:

ffmpeg -i audio.mp3 -f opus -frame_duration 20 -ar 48000 -ac 2 audio.opus

-i audio.mp3: arquivo de entrada para a codificação
-f opus: seleciona o formato Opus para saída
-frame_duration: define a duração de frames Opus a 20 milissegundos
-ar 48000: define o sample rate como 48kHz
ac 2: define a saída em modo stereo
audio.opus: arquivo de saída

De forma análoga ao yt-dlp, podemos executar o comando em Go:

    ffmpeg := exec.Command("ffmpeg", "-i", "audio.mp3", "-f", "opus", "-frame_duration", "20", "-ar", "48000", "-ac", "2", "audio.opus")
    ffmpeg.Run()

Agora, podemos executar os dois comandos e obter um áudio apropriado para o Discord. Porém, ainda temos dois problemas. O primeiro é que tudo que fizemos foi executar os dois comandos a parte. Dessa forma, teriamos um trabalho manual de baixar a música, codifica-la e salva-lá em um arquivo que apenas então seria enviado ao Discord. O que buscamos aqui é criar uma stream de áudio, sem precisar salvar arquivos em cada etapa.

O segundo problema é que o Discord requer que enviemos Opus frames, um por um. Um arquivo .opus é, na verdade, um arquivo com metadados (normalmente usando o formato/container Ogg), que encapsulam os frames. Os frames são a unidade mais básica de áudio do formato. Por essa razão, não podemos simplesmente enviar os bytes do arquivo final para a API do Discord.

Gerando uma stream de dados

Para gerar uma stream de dados, evitando que precisemos salvar o arquivo a cada etapa do processo, vamos usar o de pipes, normalmente aplicado no shell de sistemas Unix-like. No fim dessa etapa, vamos ter uma cadeia de ações que baixa o áudio do YouTube, transmite-o diretamente para o ffmpeg e então escreve seus bytes na saída padrão. O código será equivalente ao seguinte:

yt-dlp --extract-audio "https://www.youtube.com/watch?v=dQw4w9WgXcQ" -o - | \
ffmpeg -i - -f opus -frame_duration 20 -ar 48000 -ac 2 -

Atenção: não execute o comando diretamente no seu terminal, porque ele vai gerar uma saída ilegível e pode congelar seu terminal.

No comando acima, o uso de - indica entradas ou saídas padrão (stdin/stdout).
Esse processo permita que o ffmpeg leia "diratemente" do yt-dlp e então jogue sua saída para o stdout. Vamos usar isso no código Go para obter a saída sem necessidade de chamadas adicionais de leitura de arquivo.

Primeiramente, vamos criar uma pipe para a saída do yt-dlp. Isso pode ser feito com o método StdoutPipe.

dlp := exec.Command(
    "yt-dlp",
    "--extract-audio",
    "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "-o", "-",
)
pipe, err := dlp.StdoutPipe()
if err != nil {
    return err
}

O código estabelece que a saída padrão do yt-dlp irá conter os bytes do arquivo de áudio extraído. Essa saída está pode ser acessada pela variável pipe, a qual é um io.ReadCloser. Ele implementa a interface padrão de leitura do Go. Não vamos nos preocupar em fechar essa pipe pois isso será tratado depois pelo próprio pacote, na chamada de cmd.Wait.

Como discutido, o ffmpeg vai receber seu arquivo de entrada a partir da entrada padrão stdin. Dessa forma, vamos associar a pipe à entrada padrão do ffmpeg.

// ... código anterior
ffmpeg := exec.Command(
    "ffmpeg",
    "-i", "-",
    "-f", "opus",
    "-frame_duration", "20",
    "-ar", "48000",
    "-ac", "2",
    "-",
)
ffmpeg.Stdin = pipe
audioPipe, err := ffmpeg.StdoutPipe()
if err != nil {
    return err
}

Nós também fazemos um pipe com a saída do ffmpeg. Isso nos permite ler a saída diretamente no código. Agora, já podemos usufruir do resultado do ffmpeg. Para isso, basta iniciar os dois comandos.

// exemplo: usando os processos para exibir a hash sha256 do áudio
//
// ... código anterior
if err := dlp.Start(); err != nil {
    return err
}
if err := ffmpeg.Start(); err != nil {
    return err
}

data, _ := io.ReadAll(audioPipe) // ignorando tratativa de erro
fmt.Println(sha256.Sum256(data)) // exibe os bytes puros da hash

// ignorando erros
// esperamos os processos finalizar para garantir liberação de recursos
_ = dlp.Wait()
_ = ffmpeg.Wait()

Extraindo os frames Opus

Antes de enviar o áudio para o Discord, agora precisamos extrair os frames de áudio Opus do arquivo. Isso acontece porque estamos gerando arquivos .opus, com container Ogg. Primeiro, uma breve explicação de codecs e containers:

Um codec (compressor/descompressor) é responsável pela codificação ou decodificação de dados multimídia. Eles definem com a mídia deve ser representada, buscando objetivos como ocupar menos espaço, ou maior eficiência de transmissão. Um container é um formato que permite várias streams, podendo elas serem áudio, vídeo ou até legendas, em um único arquivo. O container define formatos para representar metadados, e como representar os dados "crus" do codec sendo contido.

Nesse contexto, um arquivo .opus normalmente é um arquivo que utiliza o container Ogg para armazenar áudio com o codec Opus. O Ogg é responsável por definir metadados que podem armazenar tags, comentários e também onde a stream Opus se encontra.

O formato Ogg

O Ogg organiza dados em pages (páginas). Cada page contém packets (pacotes) que são unidades menores que contém os dados brutos.

No caso de áudio Opus, as duas primeiras pages contém metadados, os quais identificam o arquivo como uma stream Opus, e dados de tags e comentários. A terceira page contém, os packets de áudio puro, os frames Opus que queremos. Cada packet é um frame.

Extraindo os frames Opus em Go

Tendo essa breve introdução aos formatos em mente, vamos extrair os frames em Go. Para isso, vamos usar um decoder do formato Ogg. O pacote é github.com/jonas747/ogg.

A seguir, um exemplo em que exibimos o tamanho de cada frame:

// assumindo código preexistente com audioPipe saindo do ffmpeg
pageDecoder := ogg.NewDecoder(audioPipe)

// pulamos as duas primeiras páginas
pageDecoder.Decode()
pageDecoder.Decode()

packetDecoder := ogg.NewPacketDecoder(pageDecoder)
for {
    packet, _, err := packetDecoder.Decode()
    if err != nil {
        break
    }
    fmt.Println("Tamanho do frame:", len(packet))
}

Isso é possível pois fizemos uma pipe da saída do ffmpeg. Ela implementa io.Reader, o qual deve ser usado para o decoder.

Enviando o áudio para o Discord

Agora que já conseguimos extrair o áudio, vamos exemplificar como fazer um bot musical do Discord. Ressalto que, como o foco dessa postagem não é sobre o bot, e sim sobre as tecnologias e o aprendizado. Portanto, a lógica do bot será simples e não interativa, focando apenas em tocar a música.

Com tudo que construimos, podemos gerar o código final. Ele consiste em usar o discordgo para inicializar um bot, conectar a um canal de voz e, então, tocar uma música utilizando os subprocessos.

package main

import (
    "fmt"
    "log/slog"
    "os"
    "os/exec"

    "github.com/bwmarrin/discordgo"
    "github.com/jonas747/ogg"
)

// atualize com seus valores
const (
    token     = "seuToken"
    guildID   = "seuGuildID"
    channelID = "seuChannelID"
)

func main() {
    if err := mainWithError(); err != nil {
        slog.Error(err.Error())
    }
}

func mainWithError() error {
    session, err := discordgo.New("Bot " + token)
    if err != nil {
        return fmt.Errorf("failed to create bot session: %w", err)
    }

    slog.Info("Opening bot session")
    if err := session.Open(); err != nil {
        return fmt.Errorf("failed to open bot session: %w", err)
    }
    defer session.Close()

    // entrar no canal de voz
    voice, err := session.ChannelVoiceJoin(guildID, channelID, false, false)
    if err != nil {
        return fmt.Errorf("failed to join voice channel: %w", err)
    }

    // configurando fonte de áudio
    dlp := exec.Command(
        "yt-dlp",
        "--extract-audio", "https://youtu.be/jDHmg8Mb9wo",
        "-o", "-",
    )
    dlpPipe, err := dlp.StdoutPipe()
    if err != nil {
        return fmt.Errorf("failed to get yt-dlp pipe: %w", err)
    }
    dlp.Stderr = os.Stderr // obter saída informativa do yt-dlp

    ffmpeg := exec.Command(
        "ffmpeg",
        "-i", "-",
        "-f", "opus",
        "-frame_duration", "20",
        "-ar", "48000",
        "-ac", "2",
        "-",
    )
    ffmpegPipe, err := ffmpeg.StdoutPipe()
    if err != nil {
        return fmt.Errorf("failed to get ffmpeg pipe: %w", err)
    }
    ffmpeg.Stdin = dlpPipe // associa saída do yt-dlp à entrada do ffmpeg
    ffmpeg.Stderr = os.Stderr

    if err := dlp.Start(); err != nil {
        return err
    }
    if err := ffmpeg.Start(); err != nil {
        return err
    }

    pageDecoder := ogg.NewDecoder(ffmpegPipe)
    pageDecoder.Decode()
    pageDecoder.Decode()

    // sinaliza ao Discord que estamos enviando áudio
    voice.Speaking(true)
    packetDecoder := ogg.NewPacketDecoder(pageDecoder)
    for {
        packet, _, err := packetDecoder.Decode()
        if err != nil {
            // esperamos que o único erro seja io.EOF
            return err
        }

        // enviando o áudio para o Discord
        voice.OpusSend <- packet
    }
}

Finalizando

Assim, podemos criar um bot simples de música. Para projetos reais, eu recomendaria outras abordagens, evitando o overhead e complexidade de subprocessos. Um projeto em potencial seria esse. Ainda seria necessário o uso do ffmpeg, para a geração de Opus, mas a coordenação de um único subprocesso é consideravelmente mais fácil.

Comente se aprendeu algo novo, se sobraram dúvidas, ou se encontrou algum erro. Eu não sou da área multimídia, e tudo que aprendi foi com esse projeto.