Blog

Práticas para comentários e nomes de arquivos SQL

Image: https://tinyurl.com/pt8ly0ix

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!

Commenting and Naming practices with T-SQL scripts

Image: https://tinyurl.com/pt8ly0ix

Do you know that feeling when you’re starting another query and this time you’re thinking “I won’t re-use this… this is a one-time thing…”. We both know you’re lying.

I said that because most of the time:

  • you’re code is reusable
  • you’re human and you forget stuff, so perhaps tomorrow you forgot something you realized how to do today
  • I’ve never seen where you keep your scripts but I bet that needs a clean up

When you’re working on something, try to picture your future self. Your older self has probably no clue about what this *really_important_2018_script* project was. Is your older/wiser version happy while reading that? I don’t think so.

If you make an effort now to be more “tidy” with your code, here’s who will be happy:

  • your future self
  • your colleagues who read your code
  • people who will take your job in the future and think “hey! this person don’t suck as much as I thought… just a little!”

How to add comments in SQL

Basically, there are two ways to add comments in SQL:

1- add “–” and start typing!

2- add “/**/” and write in between the stars.

No one is better than the other. The first option is usually for in-line smaller comment. The second it’s more for commenting out blocks of code or writing bigger comments in a way they will not be on one same line.

Initial comments

Personally, I believe comments are a good thing. It’s not something I do with every line, however, when I open a new query, I automatically add my comments.

Here’s how I like to start my scripts:

Important note: if you’re writing a stored procedure, remember to add this block of comments after your “CREATE PROCEDURE” statement. When you do so, the comment will show up when you right-click on the stored procedure and chose “Modify”. Otherwise it’s gone and saved only on your main script file.

Naming your file

Try to be descriptive when naming your file, and don’t abbreviate too much. The name you chose may seem relevant now, but again, ask yourself “is my future version hating me now?”. If the answer is yes, than chose something else.

If the script you are creating is part of a bigger project that involves other scripts, then try to start every file name with something that refers to the project itself.

For example: sp_AutomatedFinancialReports_CalculatingEmployeeSalary

Here’s what we know based on the file name:

  • sp: this is a stored procedure
  • AutomatedFinancialReports: project name that’s descriptive
  • CalculatingEmployeeSalary: this is what your specific script will do as part of the project

Avoid at all costs using “new”, “old”, “final” and relative names on your file. This is not useful long-term. If you’re creating many drafts, I’d go with versions like “v1”, “v2”, or just add the plain date to your file name. But remember this is a temporary name, and that once you figure your “v23_final_new” file, you’ll change the name accordingly. Another trick is to move your thousand drafts to a, guess what, drafts folder. The idea is that your main project folder keeps your already tested and ready to go script.

This is some basic stuff I do everyday and I hope you find it useful. Do you add something else that you’d like to share? Leave a comment (:

Want to read this post in Portuguese? Check out this link.

See you later!

Sobre mim

Como meu primeiro post oficial neste site, eu gostaria de fazer uma introdução minha, e compartilhar sobre o que eu gostaria de falar sobre, assim como meus objetivos escrevendo o blog.

Meu nome é Camila Henrique. Eu sou de Indaiatuba, uma cidade pequena de São Paulo, Brasil. Eu moro em Montreal, no Canadá, enquanto escrevo este post em Janeiro de 2021. Eu trabalho com Microsoft SQL Server desde 2015. Hoje, atuo como DBA/SQL Developer em uma agência. Por último e não menos importante, eu falo Portugues, Inglês e Francês, e adoro aprender línguas novas.

Sobre o que eu vou falar?

Eu sempre fui alguém que gosta muito de ter um mentor. Seja nos estudos ou no trabalho. Eu apenas acho que a vida fica mais fácil quando eu tenho alguém que pode me ajudar a tomar melhores decisões. Porém, eu também entendo que seja difícil encontrar um bom “mentor” para quem está começando. De jeito nenhum eu pretendo substituir esta pessoa na sua vida, mas eu gostaria de ajudar. Por isso, para você, meus queridos iniciantes em TI – eu vou falar sobre os primeiros passos que você pode tomar na sua carreira.

Se você tem interesse em SQL, está se perguntando sobre passos iniciais, ou pesquisando sobre coisas específicas dessa área de dados, eu irei postar dicas práticas que vão te ajudar na vida real.

Eu acredito que nós, humanos da área de tecnologia, frequentemente negligenciamos o poder de saber se comunicar bem com outros humanos. Não importa o que você faça, tenho certeza que seu trabalho em algum momento envolve falar com outras pessoas. E todos sabemos que nós, de TI, não somos conhecidos por desempenhar um bom papel nesse ramo da comunicação. Então, eu quero compartilhar coisas que eu aprendi sobre comunicação.

Se você, assim como eu, é alguém que fala portugues como primeira língua, eu gostaria de te ajudar nessa jornada bilíngue. Vou fazer isso postando tanto em Inglês quanto portugues, para que você possa escolher a língua e praticar como quiser. Eu adoraria fazer parte da comunidade do nosso país, assim como também não quero deixar de aproveitar a oportunidade de atingir mais pessoas com o conteúdo em inglês.

Eu também adoro falar de tópicos que envolvem diversidade no trabalho. Acredito que no nosso ramo não temos muito conteúdo. Então, esse vai ser um tópico que vai aparecer por aqui também.

Por que eu sei que gostamos de descobrir algo mais “pessoal” sobre os outros: eu gosto de yoga, amo desenhar e definitivamente eu compro mais livros do que leio, mas não recomendo que façam isso (tambem nao posso te julgar, se fizer, bem vindo ao clube!).

Eu espero passar um ótimo tempo juntos. Se você me seguir, me conta um pouco sobre você nos comentários, eu adoraria fazer mais amigos online.

Até mais!

Quer ler este post em inglês? Clique aqui.

Get to know me

Hello!

As my first official post on this site, I’d like to introduce myself, share what I’d like to talk about as well as my writing goals.

My name is Camila Henrique. I’m from Indaiatuba, a small city in São Paulo, Brazil. I am living in Montreal, Canada, as I’m writing this in January 2021. I’ve worked with Microsoft SQL Server since 2015. Today I’m a DBA/SQL Dev in a medium size agency. Last but not least, I speak Portuguese, English and French, and I love learning new languages.

What will I talk about?

I’ve always been someone who really appreciates having a mentor. Be that at school or work. I just find it better when someone can guide me towards good decisions. However, I also know how hard it is for people who are just beginning their professional life, to find a good mentor. I’m not by any means trying to replace that person in your life right now, but I’d like to help. So, for you, my dear beginner IT person – I will talk about first steps you can to take in your career.

If you’re into SQL, wondering about first steps, or searching about specific data things, I’ll post beginner tips and tricks that you can practice in real life.

I believe we, information technology humans, often misjudge the importance of knowing how to properly communicate with other humans. No matter what you do, I’m sure your work involves talking to other people, and well, we’re not really known for that. That’s why I want to share things I’ve learned about communication.

If you’re someone who natively speaks Portuguese, like me, I’d like to assist on your bilingual journey by posting in both Portuguese and English, so you can chose and practice as you’d like. I’d love to be part of my country’s community, as well as reaching more people with my English content.

I’m also passionate about topics that involve diversity at work, and sometimes I find it hard to talk about that in the tech field. That’s why this will be one of the topics I’ll present here.

And because I know people like “personal” stuff: I’m into yoga, I love drawing and I definitely buy more books than I read and do not recommend that (but won’t judge you either, welcome to the club!).

I hope we get to spend some wonderful time together. If you follow me, let me know about you in the comments, I’d love to make more internet friends.

See you!