GitHub e Mermaid: uma imagem vale mais que mil palavras
Muitas vezes no processo de desenvolvimento de software é mais fácil e direto explicar conceitos complexos com diagramas e imagens, ao invés de texto. E com a proposta de preencher esse vazio existe a ferramenta Mermaid.
Mermaid é uma ferramenta de diagramação e de gráficos simples feita em JavaScript que se propõe a utilizar uma linguagem inspirada no conhecido Markdown para renderizar e criar diagramas complexos. Isso é essencial para ajudar o processo de documentação de software, que estão cada vez maiores.
A novidade é que agora essa ferramenta tem integração nativa com o Markdown do GitHub, sendo possível adicionar facilmente aos nossos READMEs vários tipos de diagramas. Para saber mais sobre como isso funciona, esse post do GitHub explica bem o que acontece por debaixo dos panos.
Primeiros Passos
Para utilizarmos a linguagem de Mermaid no GitHub, basta utilizarmos a sintaxe comum como a seguir:
```mermaid
— códigos aqui serão renderizados e aparecerão como imagem—
```Observação: Geralmente os acentos utilizados nos textos em português quebram a renderização, então preferi escrever nas imagens seguir sem acentos.
Fluxogramas
Com isso em mente, como podemos fazer um fluxograma, um tipo de diagrama muito útil para ensinar programação? Basta seguir o exemplo do código abaixo.
```mermaid
flowchart TD
A[Início] --> B{Esta<br>chovendo<br>hoje?}
B --> C[Sim]
C --> D[Pegar<br>Guarda-Chuva]
D --> E[Fim]
B --> G[Nao] ---> E[Fim]
```Como vimos, a primeira linha diz ao GitHub para renderizar esse código em mermaid. A linha seguinte diz que tipo de diagrama queremos, nesse caso um flowchart, e sua orientação: TD é para Top Down, de cima para baixo. Outras formatações são facilmente encontradas na documentação.
A seguir no código iniciamos o fluxograma em si. Podemos deixá-lo tão complexo ou simples quanto desejarmos. Aqui a quantidade de hífens que colocamos nas setas (no mínimo 2) vão aumentar ou diminuir o comprimento dela na imagem. Ao final obtemos o seguinte resultado.
Diagrama de Classes
Também conseguimos fazer diagramas de classes, bastante utilizados em programação orientada a objetos. Com o código a seguir iniciamos as classes e suas propriedades e ligações entre si.
```mermaid
classDiagram
Veiculo <|-- Carro
Veiculo <|-- Aviao
Veiculo <|-- Motocicleta
Veiculo : +int idade
Veiculo : +int kmsRodados
Veiculo: +estaFuncionando()
Veiculo: +dirigir()
class Carro{
+String Cor
+acelerar()
+parar()
}
class Aviao{
-int tamanhoEmMetros
-decolar()
}
class Motocicleta{
+bool estaFuncionando
+acelerar()
}
```
Diagrama de Relação de Entidades
Esse tipo de diagrama é bastante útil para documentar bancos de dados, mostrando a relação que há entre os itens. Vejamos como fazê-lo.
```mermaid
erDiagram
CLIENTE ||--o{ PEDIDO : faz
CLIENTE {
string nome
string numeroDoCliente
string setor
}
PEDIDO ||--|{ ITEM : contem
PEDIDO {
int numeroDoPedido
string enderecoDeEntrega
}
ITEM {
string codigoDoProduto
int quantidade
float precoUnitario
}
```
Diagrama de Gantt
Pra quem não conhece, o diagrama de Gantt é um gráfico usado para ilustrar o avanço de tempo de diferentes etapas de um projeto. Era bastante utilizado em documentações de projetos antes do advento do desenvolvimento ágil, pois esse tipo de gráfico permitia visualizar claramente todas as etapas necessárias para o software e quanto tempo levaria.
```mermaid
gantt
title Exemplo de um Diagrama de Gantt
%% comentário
dateFormat DD-MM-YYYY
axisFormat %d-%b-%Y
section Secao 1
Tarefa 1 :a1, 01-01-2022, 30d
Tarefa 2 :after a1 , 20d
section Secao 2
Tarefa 3 :12-01-2022 , 12d
Tarefa 4 :24d
```
Gráficos de Pizza
O polêmico gráfico de pizza (ou de torta? Uma comida para cada país…) também está presente aqui no mermaid. Para fazê-lo é bem simples, basta passarmos as categorias e seus valores que o gráfico é gerado.
```mermaid
pie
title O Cientista de Dados Odeia Gráfico de Pizza?
"Sim" : 96
"Nao" : 4
```
Existem outros tipos de gráficos e diagramas mais específicos no mermaid, e todos podem ser encontrados na sua rica documentação:
