none
Comentário - Boa prática de documentação RRS feed

  • Pergunta

  • Pessoal, bom dia.

    Estou pensando em uma boa prática de comentário para código fonte de procs, views, triggers e tudo o que for desenvolvimento em SQL.

    Por exemplo, um comentário a uma proc que sofreu alteração:

    --Data 30/10/2013
    --Desenvolvedor: Glauco
    --Motivo: Adição da coluna (ID_CATEGORIA) para inserir número de chave estrangeira relacionado a categoria.

    Atualmente qual prática vocês adotam? Pela experiência, vivência, o que vocês recomendam?

    Obrigado! :D


    Glauco

    quarta-feira, 30 de outubro de 2013 14:44

Respostas

  • Glauco,

    Não existe um padrão para documentação em SQL, mas é importante manter um histórico da criação e, ao menos, da última modificação indicando sempre quem manipulou a procedure, por qual motivo e (em aplicações mais críticas) data/hora da alteração. Segue abaixo uma proposta de documentação:

    -- =============================================
    -- ALTERADO POR:  <Durval Ramos>
    -- CRIADO EM: <30/10/2013 15:12>
    -- DESCRIÇÃO:	<AJUSTE NA CONSULTA DE RETORNO>
    -- =============================================
    -- AUTOR:     <Glauco Gonçalves>
    -- CRIADO EM: <06/03/2012 08:58>
    -- DESCRIÇÃO:	<EXTRAIR DADOS DE PRODUTIVIDADE, FILTRANDO POR DATA E OPERAÇÃO>
    -- =============================================

    Se for útil para você, não esqueça de votar !

    Abraços,

    Durval Ramos
    Microsoft Partner | MTA - SQL Server 2012
    ----------------------------------
    Se foi resolvido clique "Marcar como resposta" e se foi útil "Votar como Útil"
    quarta-feira, 30 de outubro de 2013 16:45
    Moderador
  • Glauco,

    Eu costumo utilizar a documentação no cabeçalho mais ou menos da forma que o Durval demonstrou, porém adiciono uma campo "Referência" e em seguida coloco algo que identifique a alteração.

    Ai em todos os pontos do código que eu alterei eu adiciono aquela referência próximo para que fique fácil de saber o que foi alterado.


    "A vida é um paraíso, mas os homens não o sabem e não se preocupam em sabê-lo." Fiodor Dostoievski

    quarta-feira, 30 de outubro de 2013 16:51
  • Concordo com o Durval e o Kanaãm.

    Outro ponto a se considerar, principalmente com procedures e funções, é documentar também a informação dos parâmetros independente de quão intuitivos sejam. Pode parecer besteira, mas às vezes, descrever os parâmetros pode ser mais útil que resumir o que o código faz na descrição.

    Onde trabalho atualmente existe documentação a nível de metadado utilizando Extended Properties. Se for possível, é interessante documentar desta forma também, principalmente porque isso facilita DEMAIS a montagem de um dicionário de dados e fica armazenada no próprio SQL Server. Tem um artigo bacana sobre isso neste link

    []'s


    Se a resposta ajudou, classifique e ajude outros membros da comunidade.

    quarta-feira, 30 de outubro de 2013 20:48

Todas as Respostas

  • Glauco,

    Não existe um padrão para documentação em SQL, mas é importante manter um histórico da criação e, ao menos, da última modificação indicando sempre quem manipulou a procedure, por qual motivo e (em aplicações mais críticas) data/hora da alteração. Segue abaixo uma proposta de documentação:

    -- =============================================
    -- ALTERADO POR:  <Durval Ramos>
    -- CRIADO EM: <30/10/2013 15:12>
    -- DESCRIÇÃO:	<AJUSTE NA CONSULTA DE RETORNO>
    -- =============================================
    -- AUTOR:     <Glauco Gonçalves>
    -- CRIADO EM: <06/03/2012 08:58>
    -- DESCRIÇÃO:	<EXTRAIR DADOS DE PRODUTIVIDADE, FILTRANDO POR DATA E OPERAÇÃO>
    -- =============================================

    Se for útil para você, não esqueça de votar !

    Abraços,

    Durval Ramos
    Microsoft Partner | MTA - SQL Server 2012
    ----------------------------------
    Se foi resolvido clique "Marcar como resposta" e se foi útil "Votar como Útil"
    quarta-feira, 30 de outubro de 2013 16:45
    Moderador
  • Glauco,

    Eu costumo utilizar a documentação no cabeçalho mais ou menos da forma que o Durval demonstrou, porém adiciono uma campo "Referência" e em seguida coloco algo que identifique a alteração.

    Ai em todos os pontos do código que eu alterei eu adiciono aquela referência próximo para que fique fácil de saber o que foi alterado.


    "A vida é um paraíso, mas os homens não o sabem e não se preocupam em sabê-lo." Fiodor Dostoievski

    quarta-feira, 30 de outubro de 2013 16:51
  • Concordo com o Durval e o Kanaãm.

    Outro ponto a se considerar, principalmente com procedures e funções, é documentar também a informação dos parâmetros independente de quão intuitivos sejam. Pode parecer besteira, mas às vezes, descrever os parâmetros pode ser mais útil que resumir o que o código faz na descrição.

    Onde trabalho atualmente existe documentação a nível de metadado utilizando Extended Properties. Se for possível, é interessante documentar desta forma também, principalmente porque isso facilita DEMAIS a montagem de um dicionário de dados e fica armazenada no próprio SQL Server. Tem um artigo bacana sobre isso neste link

    []'s


    Se a resposta ajudou, classifique e ajude outros membros da comunidade.

    quarta-feira, 30 de outubro de 2013 20:48
  • Durval, Kanaãm e Renato, bom dia!

    Obrigadíssimo pelas dicas. Gostei muito e considero todas muito eficientes para a manutenção. Adotarei essas idéias como prática no dia-a-dia do meu trabalho.

    Renato, você está certíssimo. Uma documentação nesse nível facilita demais o momento de criar um dicionário de dados. Concordo plenamente.

    Valeu pela colaboração, pessoa. :D


    Glauco

    quinta-feira, 31 de outubro de 2013 11:49