1 + 1[1] 21 Documentação, Organização de códigos e Sistemas de versionamento
1.1 Markdown
Markdown é uma linguagem de marcação leve1, criada por John Gruber em 2004, que permite formatação de texto de forma simples e rápida, sem a necessidade de conhecimentos avançados de programação ou design. É amplamente utilizado em diversas plataformas para criar documentos, páginas web, blogs, e-mails e muito mais.
O Markdown foi projetado para ser fácil de ler e escrever, utilizando uma sintaxe simples e intuitiva. Compatível com HTML, ele pode ser convertido diretamente para outras linguagens de marcação, facilitando a publicação em diferentes plataformas.
O uso do Markdown tem se popularizado principalmente entre escritores, programadores, blogueiros e criadores de conteúdo online sem a complexidade de outras linguagens de marcação, como HTML.
Neste capítulo, veremos os conceitos básicos do Markdown e como utilizá-lo para criar conteúdo com formatação atraente e organizada.
1.1.1 Editores de Markdown
Antes de começarmos a escrever em Markdown, é útil saber que podemos utilizar qualquer editor de texto simples para criar arquivos Markdown. No entanto, existem editores específicos que oferecem recursos adicionais, como visualização em tempo real, realce de sintaxe e pré-visualização.
Alguns editores de Markdown populares são:
Visual Studio Code: Um editor de código altamente configurável que possui extensões para suporte ao Markdown. Além disso, o Visual Studio Code oferece uma pré-visualização em tempo real à medida que você digita seu conteúdo Markdown.
Atom: Outro editor de código fonte aberto com suporte ao Markdown e uma comunidade ativa de desenvolvedores. O Atom também fornece pacotes que aprimoram a experiência de escrita em Markdown.
Typora: Um editor Markdown com visualização em tempo real e uma interface de escrita amigável. O Typora é conhecido por sua abordagem “What You See Is What You Get” (WYSIWYG), o que significa que a visualização em tempo real mostra o documento final como apareceria após ser renderizado.
StackEdit: Uma ferramenta online que permite escrever e salvar seus documentos Markdown na nuvem. O StackEdit também possui uma visualização em tempo real para facilitar a visualização do resultado final. Teste Aqui
RStudio/Posit: RStudio é uma IDE (Integrated Development Environment) muito utilizada por programadores e cientistas de dados em projetos envolvendo a linguagem R. O RStudio possui um ambiente dedicado para edição de documentos R Markdown, que combina a facilidade do Markdown com a capacidade de incorporar análises e gráficos gerados pelo R.
Arquivos puramente em Markdown apresentam a extensão .md. Porém, quando utilizamos RMarkdown ou Quarto sua extensão se torna .Rmd ou .qmd, respectivamente.
1.1.2 Sintaxe Básica
1.1.2.1 Títulos
Para criar títulos em Markdown, podemos utilizar a sintaxe de hashtags (#). A quantidade de hashtags determina o nível do título.
1.1.2.2 Parágrafos e Quebras de Linha
Para criar parágrafos, basta digitar o texto normalmente. Para criar uma quebra de linha, insira dois espaços no final do parágrafo.
1.1.2.3 Ênfase
Para destacar palavras ou frases, você pode utilizar o asterisco (*) ou o sublinhado (_).
1.1.2.4 Listas
1.1.2.4.1 Lista Não Ordenada
Para criar uma lista não ordenada, utilize o asterisco (*), o sinal de mais (+) ou o traço (-) seguido do item.
1.1.2.4.2 Lista Ordenada
Para criar uma lista ordenada, digitamos o número seguido de um ponto.
1.1.2.5 Lista Aninhada
Para criar uma lista aninhada, simplesmente digitamos uma tabulação antes do indicador de lista (*, +, -, 1.).
1.1.2.6 Links
Para adicionar um link, utilizamos a sintaxe [texto](URL).
1.1.2.7 Imagens
Para inserirmos uma imagem, utilizamos a sintaxe .
Exemplo
Código
Resultado
1.1.2.8 Citações
Para adcionar uma citação, utilizamos o sinal de maior que (>).
1.1.3 Funcionalidades Avançadas do Markdown
Agora que já aprendemos os conceitos básicos do Markdown, vamos explorar algumas funcionalidades mais avançadas que tornam essa linguagem ainda mais poderosa e versátil.
1.1.3.1 Referência cruzada
As referências cruzadas permitem que você crie links para seções específicas dentro do seu documento Markdown. Isso é especialmente útil para documentos extensos, onde você deseja facilitar a navegação do leitor. Para criar uma referência cruzada precisamos atribuir um identificador único a um título usando a sintaxe {#identificador} e, em seguida, criar o link utilizando o mesmo identificador precedido de #.
Outra opção para referenciamento é utilizando o @.
1.3.0.1 Tabelas
As tabelas permitem organizar dados em formato tabular. Para criar uma tabela em Markdown, utilizamos o caractere de pipe (|) para separar as colunas e o hífen (-) na segunda linha para definir o alinhamento das células.
1.3.0.2 Blocos de Código
Para exibir blocos de código, utilizamos três acentos graves (```) seguidos do nome da linguagem de programação. Isso destacará a sintaxe de acordo com a linguagem escolhida.
Quando estamos utilizando Quarto, portanto, um arquivo .qmd o código incluído dentro do bloco delimitado será executado de acordo com a linguagem definida. Isto é, se o código dentro do bloco é um código em R, será executado como em R, se é um código em Python, será executado em Python, se é um código em Mermaid, será executado em Mermaid, e assim por diante.
1.3.0.3 Linhas Horizontais
Para criar uma linha horizontal, utilize três hífens (---).
1.3.0.4 Fórmulas Matemáticas
Se você precisa escrever fórmulas matemáticas, é possível utilizar a notação LaTeX dentro de um par de cifrões ($$). Isso permitirá que o Markdown renderize a fórmula corretamente.
Quando queremos utilizar alguma fórmula matemática dentro de um texto utilizamos apenas um cifrão $ de cada lado da equação.
1.3.1 Cheat-Sheet
Clique aqui para a cheat-sheet so material de Markdown.
1.4 Organização
As boas práticas de programação são essenciais para desenvolver código de qualidade, que seja fácil de entender, manter e evoluir. Uma das áreas importantes dentro das boas práticas é a organização dos arquivos, que ajuda a tornar o projeto mais coeso e legível.
1.4.1 Nomenclatura Adequada
A nomenclatura adequada dos arquivos é essencial para uma organização eficiente. Ao criar arquivos para projetos de análise de dados, independente da linguagem, devemos escolher nomes descritivos que reflitam o conteúdo ou a finalidade do arquivo. Por exemplo, limpeza_dados.R ou analise_exploratoria.R são nomes mais informativos do que arquivo1.R ou script_final.R.
Quando lidamos com uma sequência nas quais os códigos devem ser executados prefira salvar os códigos com nomes que indiquem essa ordem. Por exemplo, se há necessidade de que os dados sejam limpos antes de iniciarmos uma análise exploratória devemos salvar os códigos com os seguintes nomes 01_limpeza_dados.R e 02_analise_exploratoria.R, indicando a ordem na qual os códigos devem ser executados.
Ao longo do curso, utilizaremos nomes consistentes para facilitar a compreensão e a busca de arquivos relacionados.
1.4.2 Estrutura de Diretórios
A organização dos arquivos em diretórios lógicos é crucial para projetos de análise de dados. Considere uma estrutura de diretórios que abranja etapas comuns da análise, como dados para armazenar os dados brutos, codigo para conter os códigos de análise e resultados para guardar os resultados da análise.
Exemplo de estrutura de diretórios:
meu_projeto/
|-- dados/
|-- codigos/
|-- resultados/Também podemos ter essa mesma estrutura em inglês:
my_project/
|-- data/
|-- code/
|-- results/Mantendo uma estrutura organizada torna mais fácil encontrar e gerenciar os arquivos relevantes para cada etapa da análise em cada um dos projetos.
Obviamente, cada pasta pode conter sub-pastas, por exemplo, em projetos onde temos muitos dados brutos e dados processados podemos subdividir a pasta data em raw e clean, ou input e output.
my_project/
|-- data/
| |-- raw/
| |-- clean/
|-- code/
|-- results/my_project/
|-- data/
| |-- input/
| |-- output/
|-- code/
|-- results/1.4.3 Módulos e Funções Reutilizáveis
Em diversas linguagens, como R, Python, Perl, C, etc, podemos criar funções reutilizáveis para realizar tarefas específicas. Separe o código em módulos e funções para facilitar a manutenção e a reutilização em diferentes partes da análise.
Por exemplo, podemos criar um módulo limpeza_dados.R que contenha funções para lidar com a limpeza e preparação dos dados brutos. Dessa forma, essas funções podem ser reutilizadas em outras análises futuras, economizando tempo e esforço.
Também devemos nomear os arquivos de módulos e funções através de um prefixo que identifique que aquele arquivo contém funções e módulos ao invés das análises específicas para o projeto em questão. Por exemplo, identifique com o prefixo mod_, obtendo o arquivo mod_limpeza_dados.R
1.4.4 Divisão por Responsabilidade
Agrupe os arquivos de acordo com suas responsabilidades na análise. Por exemplo, separe os scripts que realizam a limpeza dos dados dos scripts que executam a análise estatística. Além disso, crie um arquivo específico para a geração de gráficos e visualizações dos resultados.
Essa abordagem facilita a manutenção do código, já que cada arquivo é responsável por uma tarefa específica.
1.4.5 Documentação
A documentação adequada é essencial para entender a análise de dados, independente da linguagem. Sempre comente o código de forma clara e inclua explicações para as etapas mais importantes da análise.
Também podemos considerar a utilização de arquivos do tipo R Markdown ou Quarto para criar relatórios interativos que combinem código, gráficos e texto explicativo em um único documento. Essa prática é excelente para comunicar os resultados da análise de forma mais clara e visual.
1.4.6 Versionamento com Git
Utilize o Git para controlar as versões do código e acompanhar o histórico de alterações. O versionamento é especialmente útil em análises de dados, pois permite que você explore diferentes abordagens e compare os resultados de diferentes versões do código.
1.4.7 Exemplo de Estrutura Completa do Projeto
my_projeto/
|-- data/
| |-- raw/
| |-- clean/
|-- scripts/
| |-- 00_limpeza_dados.R
| |-- 01_analise_estatistica.R
| |-- 02_visualizacao_resultados.R
| |-- mod_limpeza_dados.R
|-- results/
| |-- relatorio_analise.html
| |-- graficos/
| |-- grafico1.png
| |-- grafico2.png1.5 Sistemas de Versionamento
Versionamento de Código refere-se ao controle cuidadoso das alterações feitas em um projeto de software ao longo do tempo. Isso é realizado através de um sistema de controle de versão, como o Git, que registra todas as modificações no código-fonte do projeto. Cada conjunto de mudanças é registrado em uma versão, permitindo que os desenvolvedores acessem e revertam as alterações conforme necessário.
Um sistema de controle de versão é uma ferramenta essencial para o desenvolvimento colaborativo, permitindo que várias pessoas trabalhem em um mesmo projeto sem conflitos e de maneira mais organizada. O Git é um exemplo de sistema de versionamento de códigos, que pode ser hospedado no GitHub, por exemplo.
1.5.1 Git
Git é um sistema de controle de versão distribuído. Foi criado por Linus Torvalds em 2005 e é amplamente utilizado na indústria de desenvolvimento de software. O Git permite que desenvolvedores rastreiem mudanças no código-fonte ao longo do tempo, facilitando o trabalho em equipe e a colaboração. Ele oferece recursos para criar ramos (ramificações) do código, mesclá-los e reverter alterações, permitindo que os desenvolvedores experimentem diferentes abordagens sem afetar a versão principal do projeto. O Git é executado localmente no computador do desenvolvedor e não requer uma conexão com a internet, a menos que você queira sincronizar com um repositório remoto, como o GitHub.
1.5.2 GitHub
O GitHub é uma plataforma de hospedagem de código-fonte e colaboração baseada em Git. Lançado em 2008, o GitHub tornou-se rapidamente um dos maiores repositórios de código-fonte do mundo. Ele permite que os desenvolvedores hospedem seus repositórios Git na nuvem e colaborem com outros membros da equipe ou contribuidores externos. O GitHub facilita o compartilhamento de código, rastreamento de problemas (issues), solicitações de pull (pull requests) e revisão de código. Além disso, fornece uma interface amigável para visualizar histórico de alterações, ramos, problemas e outras informações importantes relacionadas ao desenvolvimento do software.
1.5.3 Importância do Versionamento de Código
1. Rastreamento de Alterações: Com o versionamento de código, é possível rastrear todas as modificações feitas no projeto, incluindo quem realizou cada alteração e quando. Isso facilita a identificação de problemas e a compreensão do histórico do projeto.
2. Reversão Segura: Caso um erro seja introduzido no código, é possível reverter para uma versão anterior que esteja funcionando corretamente. Isso é especialmente útil em situações de bugs críticos ou mudanças indesejadas.
3. Colaboração Eficiente: Equipes de desenvolvimento podem trabalhar em paralelo em diferentes partes do projeto, sem interferir no trabalho um do outro. O versionamento permite que cada desenvolvedor trabalhe em sua própria cópia (branch) do código antes de integrá-lo ao projeto principal.
4. Testes e Experimentações: É possível criar branches para testar novos recursos, correções ou experimentações sem impactar o código principal. Esses branches podem ser compartilhados com colegas para revisão antes de serem incorporados.
5. Backup e Segurança: Os repositórios versionados atuam como um backup seguro para o código-fonte do projeto. Em caso de falha no hardware ou perda de dados local, as versões remotas do código podem ser recuperadas.
1.5.4 Criando uma Conta no GitHub
GitHub é uma plataforma popular para hospedar projetos versionados usando o Git. Siga os seguintes passos para criar uma conta:
Acesse o site oficial do GitHub em https://github.com/.
Clique em “Sign Up” ou “Criar conta”.
Preencha seus dados, incluindo nome de usuário, endereço de e-mail e senha.
Selecione um plano de conta.
Conclua o processo de criação de conta seguindo as instruções na tela.
1.5.5 Mantendo Projetos e Colaborando no GitHub
1. Repositórios: Após criar uma conta no GitHub, você pode criar um novo repositório ou clonar (fazer uma cópia local) um repositório existente para começar a trabalhar no projeto.
2. Commits: Os commits são registros das alterações feitas no código. Ao fazer um commit, é importante fornecer uma mensagem clara e concisa que explique o que foi alterado. Isso ajuda na compreensão das mudanças realizadas em cada versão.
3. Branches: Os branches permitem que você crie cópias do seu repositório para trabalhar em funcionalidades específicas ou correções. Branches são úteis para desenvolver recursos em paralelo sem afetar o projeto principal. Quando um trabalho em um branch estiver concluído, ele pode ser mesclado ao projeto principal através de um pull request.
4. Pull Requests: Um pull request é uma solicitação para mesclar as alterações de um branch ao projeto principal. É uma etapa crucial para a colaboração, pois permite que outros membros da equipe revisem as mudanças, façam comentários e discutam as alterações antes de serem integradas ao código principal.
5. Forks: Quando você deseja contribuir para um projeto mantido por outra pessoa, pode criar um fork, que é uma cópia independente do repositório original em sua conta do GitHub. Após fazer as alterações em seu fork, você pode enviar um pull request para o repositório original, sugerindo que suas mudanças sejam incorporadas ao projeto principal.
1.5.6 Comandos Básicos do Git
Aqui estão os comandos essenciais do Git que ajudarão você a começar com o versionamento de código:
git init: Inicializa um novo repositório Git em um diretório vazio ou converte um projeto existente em um repositório Git.git clone: Cria uma cópia local de um repositório Git existente. Você pode clonar um repositório do GitHub ou de outro servidor Git.git add: Adiciona arquivos ao índice (staging area) para serem incluídos no próximo commit. Use “git add .” para adicionar todos os arquivos modificados.git commit: Registra as alterações adicionadas ao índice como uma nova versão no histórico do repositório. Lembre-se de fornecer uma mensagem significativa usando o parâmetro “-m”.git status: Exibe o estado atual do seu repositório, mostrando os arquivos modificados, adicionados e aqueles que ainda não foram monitorados pelo Git.git log: Mostra o histórico de commits do repositório, incluindo os autores, datas e mensagens de commit.git branch: Lista todas as branches do repositório. O branch atual é marcado com um asterisco.git checkout: Permite alternar entre branches. Use “git checkout -b nome-do-branch” para criar e alternar para um novo branch.git merge: Mescla as alterações de um branch específico no branch atual. Use após realizar um pull request ou ao concluir o trabalho em um branch paralelo.git pull: Puxa as alterações do repositório remoto para o seu repositório local. É uma combinação dos comandos “git fetch” e “git merge”.git push: Envia as alterações do seu repositório local para o repositório remoto (por exemplo, GitHub). Use “git push origin nome-do-branch” para enviar um branch específico.git remote: Exibe informações sobre os repositórios remotos conectados ao seu projeto.git fetch: Busca as alterações do repositório remoto, mas não as mescla automaticamente em seu repositório local.git rm: Remove arquivos do repositório e os prepara para serem removidos do controle de versão.git diff: Mostra as diferenças entre o código no diretório de trabalho e as alterações confirmadas.
1.5.7 Cheat-Sheet Git
Clique aqui para a cheat-sheet do material de Git.
1.5.8 Cheat-Sheet RStudio & Git
Clique aqui para a cheat-sheet do material de Git & Rstudio.
1.6 Recursos extras
Alguns recursos extras que podem ser utilizados:
conjunto de sinais e códigos aplicados a um texto ou a dados para para definir formatos, maneiras de exibição e padrões. Ao contrário de linguagens de programação, não possui estruturas de controle como os comandos condicionais e de repetição.↩︎