Usuário com melhor resposta
Comentário - Boa prática de documentação

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
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 RamosMicrosoft Partner | MTA - SQL Server 2012---------------------------------- Se foi resolvido clique "Marcar como resposta" e se foi útil "Votar como Útil"- Sugerido como Resposta Durval RamosModerator quarta-feira, 30 de outubro de 2013 16:45
- Marcado como Resposta Glauco Vinicio Gonçalves Albuquerque quinta-feira, 31 de outubro de 2013 11:49
-
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
- Sugerido como Resposta Kanaãm Luz Romero Rodrigues quarta-feira, 30 de outubro de 2013 16:52
- Marcado como Resposta Glauco Vinicio Gonçalves Albuquerque quinta-feira, 31 de outubro de 2013 11:49
-
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.
- Marcado como Resposta Glauco Vinicio Gonçalves Albuquerque quinta-feira, 31 de outubro de 2013 11:49
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 RamosMicrosoft Partner | MTA - SQL Server 2012---------------------------------- Se foi resolvido clique "Marcar como resposta" e se foi útil "Votar como Útil"- Sugerido como Resposta Durval RamosModerator quarta-feira, 30 de outubro de 2013 16:45
- Marcado como Resposta Glauco Vinicio Gonçalves Albuquerque quinta-feira, 31 de outubro de 2013 11:49
-
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
- Sugerido como Resposta Kanaãm Luz Romero Rodrigues quarta-feira, 30 de outubro de 2013 16:52
- Marcado como Resposta Glauco Vinicio Gonçalves Albuquerque quinta-feira, 31 de outubro de 2013 11:49
-
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.
- Marcado como Resposta Glauco Vinicio Gonçalves Albuquerque quinta-feira, 31 de outubro de 2013 11:49
-
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