A Convenção de Nomenclatura que Vai Transformar Seu Código de Machine Learning

Você conhece aquela sensação de abrir um código antigo e não fazer ideia do formato de um tensor? O clássico outputs não diz nada — é batch first ou batch last? Inclui sequência? Alguém reshapou isso em algum lugar?

Pois bem, existe uma técnica absurdamente simples que resolve isso de vez.

O Que São Shape Suffixes

A ideia é colar letras minúsculas no final dos nomes de variáveis para indicar as dimensões do tensor. Em vez de outputs, você escreve outputs_bc. Em vez de activations, escreve activations_bcn.

Parece mais trabalho? No começo pode parecer. Mas acredite — essa convenção é um dos investimentos com melhor retorno que você pode fazer em qualquer projeto de ML.

O Alfabeto das Dimensões

Aqui está a referência rápida:

• b — dimensão de batch
• p — posição ou índice na sequência
• n — neurônios (resultado de multiplicação por matriz de pesos)
• c — canais
• h — altura (para imagens)
• w — largura (para imagens)
• d — profundidade (dados 3D)
• k — dimensão de kernel

Com isso, logits_bc já diz tudo: batch de logits com dimensão de canal — ideal para classificação. E positional_embeddings_bpn deixa claro que você tem batch, posição e neurônios nessa ordem.

Por Que Vale a Pena Adotar

Contexto instantâneo. Ao ver probs_bc, você sabe de cara que está olhando probabilidades organizadas por batch e classe. Sem precisar caçar documentação ou reler o código inteiro.

Detecção automática de erros. Aqui é onde a mágica acontece. Se você escrever:

outputs_bc = torch.matmul(activations_bcn, weights_bcn)

O erro salta aos olhos. A matriz de pesos deveria ser weights_nc para multiplicar corretamente com activations_bcn. Os próprios nomes das variáveis viram um verificador estático de formatos.

Documentação que não fica obsoleta. Comentários são esquecidos, ninguém atualiza quando refatora. Mas embeddings_bpn continua preciso sempre — porque o nome da variável É a documentação.

Code reviews mais tranquilas. Quem está revisando consegue identificar mismatches de dimensão sem precisar rodar o código ou sair rastreando funções. Isso economiza tempo e pega bugs antes.

Padrões que Você Vai Usar Na Prática

Para concatenções e stacks: Quando combina tensores, ajuste o sufixo. Fez stack de dois features_bc em um novo eixo? Agora é features_bck — ou features_bkc, depende de qual eixo escolheu.

Para reduções: Somou sobre a dimensão de posição? inputs_bp vira inputs_b. Fez argmax nos canais? logits_bc vira logits_b. O sufixo encolhe junto com a dimensionalidade real.

Para tensores mais complexos: Pode combinar quantas letras precisar: attention_bppn para atenção entre pares de posição, ou gradients_bpn para gradientes por batch, posição e neurônio.

Como Fazer Funcionar

O segredo é consistência radical. Adote a convenção e use em tudo — inputs, outputs, cada variável intermediária. Sim, até aquela que você criou num one-liner só pra debugar.

Seu eu do futuro vai agradecer. Sua equipe também.

Se você trabalha construindo aplicações de ML e quer código limpo que escala com o time, pequenas convenções assim se acumulam em ganhos enormes de produtividade. É o mesmo princípio de boa nomenclatura em qualquer parte do desenvolvimento — faça o código falar por si.

Experimente por uma semana no seu próximo projeto. Aposto que depois você vai se perguntar como conseguiu viver sem isso.