Conhece o sentimento de abrir um novo arquivo, e pensar “eu não vou reutilizar esse código… só vou fazer isso uma vez…”. Nós dois sabemos que você está mentindo.
Eu estou falando isso pois, na maior parte do tempo:
- seu código é reutilizável
- você é humano e esquece as coisas. Então, talvez amanhã você já tenha esquecido como resolver uma coisa que você fez hoje.
- eu nunca vi onde você salva seus scripts mas eu aposto que você poderia fazer uma boa limpeza na sua pasta
Quando você está trabalhando em algo, tente se imaginar no futuro. O seu “eu” mais velho provavelmente não tem ideia do que seja o *projeto_importante_2018_script*. O seu eu mais experiente está feliz lendo este arquivo? Eu acho que não.
Se você fizer um esforço agora para ser mais “arrumadinho” com o seu código, essas pessoas vão ficar muito felizes:
- o seu eu futuro
- seus colegas de trabalho que leem seus códigos
- pessoas que vão assumir seu lugar no futuro, e vão pensar “olha só! essa pessoa não era tão péssima, era apenas ruim mesmo!”
Como adicionar comentários em SQL
Basicamente, existem duas maneiras de adicionar comentários em SQL:
1- adicione “–” e comece a digitar!
2- adicione “/**/” e escreva entre os asteriscos.
Nenhum é melhor que o outro. A primeira opção é mais usada para comentários na mesma linha do código. A segunda, é mais comum para comentar blocos de código, ou escrever comentários maiores que não vão ficar em uma linha gigante.
Comentários iniciais
Pessoalmente, eu acredito que comentários são algo bom. não é algo que eu faça em cada linha do código, porem, quando eu abro uma nova query, automaticamente eu adiciono um cabeçalho de comentários.
Eu começo meus scripts da seguinte forma:
Autor: quem está escrevendo o script.
Data: quando o script foi criado, para edições eu geralmente adiciono um edit na mesma linha.
Projeto: qual projeto o script faz parte. É legal descrever um pouco o projeto.
Descrição: descrever a razão do seu script, aqui é onde você explica onde está parte se encaixa no todo.
Requisitado por: nome de quem pediu que isso fosse desenvolvido. Além dos nomes, talvez seja interessante adicionar também os emails para contato.
Importante: se você está escrevendo uma stored procedure, lembre-se de adicionar o seu bloco de comentários depois do comando “CREATE PROCEDURE”. Fazendo isso, o seu comentário vai estar integrado ao código da proc, e vai aparecer inclusive quando você escolher a opção de “modificar” o arquivo. Se você não fizer assim, o comentário vai ficar salvo apenas no próprio arquivo principal do script.
Dando um nome ao arquivo
Tente ser descritivo e intuitivo quando for nomear seu arquivo, e não abrevie muito. O nome que você escolheu pode parecer relevante na hora, mas de novo, pergunte-se se o seu eu do futuro está te odiando agora.
Se o seu script fizer parte de um projeto maior, então tente começar o nome do arquivo como algo que remeta ao projeto.
Por exemplo: sp_RelatorioFinancasAutomatico_CalculoSalarioFuncionario
Com esse nome, sabemos:
- sp: isso é uma stored procedure
- RelatorioFinancasAutomatico: nome descritivo do projeto
- CalculoSalarioFuncionario: o que a sua parte especifica do script faz
Evite usar termos como “novo”, “velho”, “final”, dentre outros. Isso não é útil em longo prazo. Se você está criando vários rascunhos, por exemplo, seria interessante versionar, usando “v1”, “v2”, ou até adicionar a data no nome do arquivo. Mas, lembre-se que esses nomes deveriam ser temporários, e assim que você descobrir qual finalmente é sua versão “v23_final_novo”, mude esse nome. Outra coisa que você pode fazer é mover seus rascunhos para uma sub-pasta dentro do projeto, assim fica mais fácil de organizar os scripts “finais” e importantes.
Essas são coisas básicas que eu faço todos os dias. Espero que você tenha achado útil. Existe outra coisa que você adiciona que gostaria de compartilhar? Deixe seu comentário (:
Quer ler este post em Inglês? Clique aqui.
Até mais!
Camila Henrique 