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

Question

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

Answer 1

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"

Answer 2

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

Answer 3

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.

Answer 4

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