Opção Vírgulas

A posição das vírgulas define se cada vírgula vai no fim da linha (à direita, o padrão) ou no início da linha seguinte (à esquerda). Esta página mostra as duas saídas, onde a opção se aplica e os prós e contras práticos, para que você escolha um estilo para o seu time.

O que a opção faz

Sempre que o formatador coloca os itens de uma lista separada por vírgulas em linhas diferentes, ele precisa escolher qual linha recebe a vírgula. A opção faz essa escolha para todas as listas desse tipo na instrução:

• a lista do select;
• as listas de GROUP BY e ORDER BY;
• os argumentos de função, quando uma chamada é quebrada com um argumento por linha;
• listas de valores como IN ('OPEN', 'FROZEN'), que também são quebradas com um valor por linha;
• a lista do SET de um UPDATE, a lista do RETURNING e as listas de colunas e de VALUES de um INSERT;
• as definições de colunas no CREATE TABLE (,amount NUMERIC(12, 2));
• as consultas nomeadas de uma cláusula WITH (,ranked AS ();
• itens do select que são expressões CASE (,CASE WHEN).

A mesma regra vale em qualquer nível de aninhamento: dentro de uma CTE ou de uma subconsulta, as vírgulas ficam na coluna de indentação do próprio bloco.

Nada mais muda: as quebras de linha, a indentação e a caixa das palavras-chave são as mesmas nos dois modos.

Valores possíveis e padrão

Esta é a mesma consulta de relatório nos dois estilos:

select c.id, c.email, c.country_code, count(o.id) as order_count, sum(o.total) as lifetime_value from customers c left join orders o on o.customer_id = c.id group by c.id, c.email, c.country_code order by lifetime_value desc, c.id

SELECT c.id,
    c.email,
    c.country_code,
    COUNT(o.id) AS order_count,
    SUM(o.total) AS lifetime_value
FROM customers c
    LEFT JOIN orders o
        ON  o.customer_id = c.id
GROUP BY c.id,
    c.email,
    c.country_code
ORDER BY lifetime_value DESC,
    c.id

SELECT c.id
    ,c.email
    ,c.country_code
    ,COUNT(o.id) AS order_count
    ,SUM(o.total) AS lifetime_value
FROM customers c
    LEFT JOIN orders o
        ON  o.customer_id = c.id
GROUP BY c.id
    ,c.email
    ,c.country_code
ORDER BY lifetime_value DESC
    ,c.id

Nas duas saídas, o primeiro item fica na linha da sua palavra-chave (SELECT c.id, GROUP BY c.id, ORDER BY lifetime_value DESC). Com vírgulas à esquerda, cada item seguinte começa com uma vírgula na coluna da indentação, de modo que as vírgulas formam uma linha vertical reta.

As vírgulas à esquerda são aplicadas da mesma forma aos argumentos de função e às listas de valores:

SELECT id
    ,COALESCE(
        nickname
        ,first_name
    ) AS display_name
    ,round(
        balance
        ,2
    ) AS balance
FROM accounts
WHERE status IN (
    'OPEN'
    ,'FROZEN'
)

Vírgulas à direita: prós e contras

As vírgulas à direita seguem a pontuação normal, então a consulta se lê como uma lista num texto corrido. É o estilo usado na maior parte da documentação dos bancos de dados, no SQL gerado por ferramentas e pela maioria dos desenvolvedores que nunca pararam para pensar no assunto. Quem chegar novo ao seu código não vai estranhar.

O custo aparece no fim da lista. O último item não tem vírgula, então ele se comporta de forma diferente de todos os outros. Comente-o durante uma depuração e o item anterior fica com uma vírgula logo antes do FROM:

SELECT c.id,
    c.email,
    c.country_code,
    COUNT(o.id) AS order_count,
    -- SUM(o.total) AS lifetime_value
FROM customers c
    LEFT JOIN orders o
        ON  o.customer_id = c.id

A maioria dos bancos de dados, incluindo PostgreSQL, MySQL, SQL Server e Oracle, rejeita essa instrução com um erro de sintaxe perto do FROM. É um dos erros de SQL autoinfligidos mais comuns, e ele pode se repetir toda vez que alguém acrescenta ou remove a última coluna e esquece a vírgula da linha de cima.

Vírgulas à esquerda: prós e contras

As vírgulas à esquerda transferem o caso especial do último item para o primeiro. Cada item depois do primeiro carrega a sua própria vírgula, então remover ou comentar a última linha deixa o SQL válido:

SELECT c.id
    ,c.email
    ,c.country_code
    ,COUNT(o.id) AS order_count
    -- ,SUM(o.total) AS lifetime_value
FROM customers c
    LEFT JOIN orders o
        ON  o.customer_id = c.id

A linha vertical de vírgulas também deixa fácil perceber uma vírgula faltando. Isso importa mais do que parece: na maioria dos bancos de dados o AS é opcional nos aliases de coluna, então uma vírgula esquecida entre duas colunas não gera erro. Ela transforma silenciosamente a segunda coluna num alias da primeira. Com vírgulas à esquerda, o buraco na coluna de vírgulas aparece à primeira vista; com vírgulas à direita, ele se esconde na borda direita irregular.

As desvantagens são a familiaridade e o gosto. Muitos desenvolvedores acham estranha uma linha que começa com pontuação, e o código copiado da documentação ou de outros projetos vai estar no outro estilo até ser formatado. O problema também não desaparece, ele muda de lugar: remover ou comentar o primeiro item ainda exige editar a linha do SELECT.

Efeito nos diffs e na revisão de código

A diferença fica mais fácil de ver no controle de versão. Usando o layout acima, esta é a quantidade de linhas alteradas em edições comuns:

Colunas são acrescentadas no fim de uma lista com muito mais frequência do que no início, então as vírgulas à esquerda geram diffs um pouco menores e menos comentários de revisão sobre uma vírgula perdida. O efeito é real, mas modesto; a consistência em toda a base de código importa mais. O guia de revisão de código e controle de versão mostra como trocar de estilo sem poluir o histórico.

Qual escolher

Os dois estilos aparecem em guias de estilo publicados por times, e nenhum deles está errado. As vírgulas à esquerda têm muitos adeptos entre os times de dados e de analytics que editam listas longas de select o dia inteiro; as vírgulas à direita continuam sendo o padrão mais comum nos demais contextos. Como regra prática:

• Escolha à direita se o SQL for lido principalmente por desenvolvedores de aplicação, se ele estiver embutido em outro código ou se você quiser uma saída parecida com a da documentação.
• Escolha à esquerda se o seu time escreve consultas de relatório longas, comenta e descomenta colunas enquanto explora os dados ou já foi vítima do problema do alias causado pela vírgula esquecida.

Seja qual for a escolha, deixe o formatador aplicá-la, para que ninguém precise lembrar da regra. O guia de vírgulas à esquerda e à direita se aprofunda na história e nos argumentos dos dois lados. As outras opções estão documentadas nas páginas de espaços de indentação, quantidade máxima de colunas, caixa das palavras-chave e parênteses em nova linha.