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!