SQL Clean - passo a passo para uma boa documentação

[kassia.andrade]

Olá pessoal, tudo bem ? 

Quem nunca se deparou com um código legado e demorou um pouco para entender mesmo com 
um bom conhecimento da linguagem em questão? 
Vou citar alguns steps simples utilizando a linguagem SQL como exemplo
para termos códigos clean pensando sempre em quem vai ler este no futuro.

Algumas questões para considerar: 

1 - Indentação 

Procure organizar seu código, quanto maior for o código maior a dificuldade de compreensão.
Por isso sempre deixe organizado de uma forma lógica e de fácil entendimento.

Exemplo de cógigo sem indentação: 

 

SELECT tabela_exemplo1.a,tabela_exemplo1.c,tabela_exemplo2.b,
row_number() over (partition by tabela_exemplo2 order by data_a desc)  --comentários 
FROM 
tabela_exemplo1 

Exemplo de código indentado: 

SELECT 
    tabela_exemplo1.a,
    tabela_exemplo1.c,
    tabela_exemplo2.b,
    row_number() over (partition by tabela_exemplo2 order by data_a desc)  --comentários 
FROM 
    tabela_exemplo1 

2 - Formatos acessíveis. 

Procure utilizar CTEs ao invés de subqueries.
As CTEs começam de cima para baixo, as subqueries começam do meio do código e vai irradiando para cima e 
para baixo,o que torna um pouco mais demorado para entender conforme o tamanho do código. 
Se preferir criar subqieries não há problema desde que o código esteja devidamente comentado,indentado, com alias adequados e reduzido 
ao máximo, evitando pergaminhos. 

Exemplo de CTE:

with motivos_tbA_tbB as (  --começo do código 

SELECT 
    tabela_exemplo1.a,
    tabela_exemplo1.c,
    tabela_exemplo2.b,
    row_number() over (partition by tabela_exemplo2 order by data_a desc)   
FROM 
    tabela_exemplo1 
LEFT JOIN tabela_exemplo2 ON tabela_exemplo1.a= tabela_exemplo2.a
LEFT JOIN tabela_exemplo3 datas  ON tabela_exemplo3.data  = date_trunc('month',tabela_exemplo2.data)
LEFT JOIN shop_cadempresa ON  shop_cadempresa.handle = shop_contratos.id_empresa

)
SELECT 
    COUNT (c) qtd_vendida  ,  --final do código 
    a  AS motivo_venda
FROM
    motivos_tbA_tbB

Exemplo de Subquery:

 

SELECT 
    COUNT (c) qtd_vendida  , --final do código 
    a  AS motivo_venda
FROM
    (
    SELECT    --começo do código 
        tabela_exemplo1.a,
        tabela_exemplo1.c,
        tabela_exemplo2.b,
        row_number() over (partition by tabela_exemplo2 order by data_a desc) 
    FROM 
        tabela_exemplo1 
    LEFT JOIN tabela_exemplo2 ON tabela_exemplo1.a= tabela_exemplo2.a
    LEFT JOIN tabela_exemplo3 datas  ON tabela_exemplo3.data  = date_trunc('month',tabela_exemplo2.data)
    LEFT JOIN shop_cadempresa ON shop_cadempresa.handle = shop_contratos.id_empresa
    ) motivos_tbA_tbB   

3 - Comentarios úteis.

Crie comentários uteis no código, caso seja uma formula complexa ou que exija uma explicação maior 
faça um breve comentário e coloque a explicação da lógica  na propria documentação do código. 

4 - Alias  uteis e não x, y ,z ..

Na correria do dia dia  é mais fácil colocar um x,y..z mas isso não deixa muito claro 
a lógica do código pra quem vê pela primeira vez.

Exemplo de alias sem identificação : 

select   --parte3
 *
from
   (     select   --parte 2
            *
        FROM
        (
            select   --parte 1 
                * 
            from 
                A
            where 
                ativo is true   

        )x 
    )y

Exemplo de  alias com identificação:

with contratos_ativo as (     --parte 1
    select 
        * 
    from 
        A
    where 
        ativo is true  
    ),
clientes as (     --parte2

    select 
        * 
    from 
        contratos 
    )
select    --parte 3
    *
from
    clientes

5 - Tamanho do código.

Procure enxugar ao máximo o código para não virar o famoso pergaminho.

Exemplo final:

with motivos_tbA_tbB as (  

SELECT 
    tabela_exemplo1.a,
    tabela_exemplo1.c,
    tabela_exemplo2.b,
    row_number() over (partition by tabela_exemplo2 order by data_a desc) /*faça comentarios uteis */
FROM 
    tabela_exemplo1 
LEFT JOIN tabela_exemplo2 ON tabela_exemplo1.a= tabela_exemplo2.a
LEFT JOIN tabela_exemplo3 datas  ON datas.data  = date_trunc('month',tabela_exemplo2.data)
--caso queria dar um alias na tabela não tem problema desde de que seja um nome util e não x..z..y 
LEFT JOIN shop_cadempresa ON shop_cadempresa.handle = shop_contratos.id_empresa

)
SELECT 
    COUNT(c) qtd_vendida,
    a  AS motivo_venda
FROM
    motivos_tbA_tbB
WHERE

    row_number = 1 
/*faça comentarios uteis */
GROUP BY 2
ORDER BY 1 ASC

Um código bem documentado poupa tempo de leitura,entendimento e manutenção ao se tornar um legado.
A indentação ajuda a achar as palavras chaves no código de uma forma mais rápida, a organização do 
código começando de uma forma lógica de cima pra baixo usando a CTE ajuda a encontrar mais rápido os 
pontos chave do código e usando alias que represente cada parte do código ajuda a entender melhor a lógica
usada e consequentemente oque esta acontecendo na query,ficando mais claro o entendimento.