top of page

Databricks - Documentando seus notebooks

Fala dataholics, daquela série de dicas rápidas, hoje mostrarei uma maneira que você pode utilizar para documentar seus notebooks.


O que veremos nesse post:

  • Documentação é coisa séria

  • Magic commands

  • Markdown

  • Criando uma tabela com Markdown

  • Adicionando imagens no seu notebook

  • ChatGPT o quê?


 

Documentação é coisa séria, mas infelizmente é geralmente deixada de lado devido à prioridade de outras demandas, isso acaba impactando na vida dos engenheiros e desenvolvedores no dia a dia.


As dicas que darei aqui não seguem uma convenção universal ou um framework padrão, existem inúmeras maneiras e ferramentas para realizar uma boa documentação, existem os que não gostam de comentários e documentações no código e há quem goste de ter uma documentação no código através de comentários, mas o intuito desse post não é causar intrigas rs, siga o padrão da sua empresa ou aquele te deixa mais confortável, mas, NÃO deixe de documentar.


Quem nunca pegou um código assim, sem documentação nenhuma?

Esse pelo menos foi muito criativo, a pessoa que pegou esse código com certeza riu muito, mas, depois gastou 1 semana pra entender esse trecho de código hahaha.


Ou aqueles comentários clássicos hahaha.


Os memes e piadas são muito divertidos, mas sabemos que na vida real isso pode custar empregos e carreiras, documentação é sim coisa séria e geralmente negligenciada, por acharem que o desenvolvedor estar codificando é mais produtivo, contudo, esquecem que aquele código irá precisar de suporte, em alguns casos pelo próprio desenvolvedor, e sem documentação, nem ele mesmo vai lembrar o que fez.


Se você já pegou um código ou ambiente complexo sem documentação entenderá bem, então, faz a sua parte, documente nem que seja num papel de pão.

 

Bom falando de Databricks, trabalhamos em notebooks certo? Se você ainda não conhecia, temos os magic commands que nos ajudam a trocar a linguagem da célula\comando, ou seja, seu notebook pode estar no formato de python, mas você pode usar outras linguagens dentro dele, isso é sensacional, ter um script escrito em várias linguagens é algo assustador para alguns devs rsrs.


Esses são os magics commands disponíveis:

  1. %sql

  2. %python ou %py

  3. %scala

  4. %r

  5. %sh

  6. %fs

  7. %md - Esse é o nosso tema

  8. %run

No mesmo notebook você pode utilizar os 8 juntos:

Observação: O magic command precisa ser sempre a primeira linha do comando.



 

Sabendo disso, podemos usar Markdown para documentarmos trechos dos nossos notebooks, ou pelo menos o contexto principal, para quem abrir o notebook já saber do que se trata, como executar e particularidades.


Gosto sempre de colocar a primeira célula dos notebooks com uma documentação do contexto principal, mesmo que toda essa documentação esteja em outra ferramenta como um Word, Wiki, base de conhecimento, etc. Adicionando esse contexto no notebook pode facilitar e agilizar o entendimento de quem está interpretando ou investigando um problema. Claro que tudo que é demais acaba ficando ruim, tome cuidado para não ter mais Markdown do que o próprio código, pode poluir muito a visualização.


É muito comum para outras ferramentas e linguagens os desenvolvedores criarem um arquivo Markdown de documentação, assim como se vê no próprio Github os arquivos README.

É bem comum todos os repositórios terem seu arquivo Markdown com uma boa documentação.


Bom, chega de falar, vamos a um exemplo prático de documentação.


Se você já viu alguns notebooks no meu github notará que todos têm uma documentação base na primeira célula.


Vou mostrar como faço esse primeiro comando do notebook.


Ah Reginaldo, mas não manjo nada de MarkDown! Calma, é mais fácil do que você imagina, tem muito site bom e fácil de achar documentações, o próprio Wikipedia que já deixei la em cima e deixo uma introdução básica para você que esta iniciando:


 

Mostrarei 2 exemplos clássicos:

  • Criando uma tabela em Makdown

  • Adicionando imagens no seu Notebook

Adicionando uma tabela:

Primeiro passo, altere o comando para Markdown com o %md.

O formato de uma tabela é basicamente criada com uso de pipes "|", ele que define a separação das colunas.


Agora vamos adicionar uma imagem no nosso notebook:


Para adicionarmos uma imagem basta referenciarmos a URL dela nesse formato, você pode pegar qualquer imagem da Internet.

![Nome da imagem](https://[endereço da imagem])

O resultado será igual abaixo.

Com markdown a imaginação e criatividade é o limite.

 

Bom, já vimos que é fácil trabalhar com Markdown, mas, da pra ser mais fácil ainda?


Fiz um teste com ChatGPT e o resultado foi bacana, segue abaixo o que pedi e o que ele me entregou.


Eu pedi para ele documentar esse meu script que já está no github:


O que ele me devolveu:



O resultado copiando e colando ficou assim:

Ele adicionou o nome da minha função como titulo, criou a tabela do jeito que imaginei e deixou 3 exemplos bem próximos do que imaginei.

Sim, os exemplos funcionam!

Só acrescentei algumas quebras de linhas e juntei os exemplos, e o resultado ficou satisfatório, o que você acha?


Bom é isso, espero que te ajude.


Link desse exemplo no meu github:


Fique bem e até a próxima.


1.269 visualizações0 comentário

Posts recentes

Ver tudo

Comments


Post: Blog2 Post
bottom of page