Olá techs! 💕
Você já passou pela experiência de passar noites em claro escrevendo um código complexo, deixá-lo guardado por duas semanas e, ao tentar lê-lo novamente para fazer um pequeno ajuste, olhar para a tela e pensar:
“Quem escreveu essa bagunça e o que essa função faz de verdade?”? 😅
A capacidade de escrever códigos funcionais é essencial, mas existe uma habilidade igualmente vital e muito negligenciada em cursos de TI:
Saber documentar seu código.
Programar não é apenas dar instruções para o computador executar; é explicar para outros seres humanos (inclusive para o seu “eu” do futuro) como o sistema funciona.
Hoje vamos aprender boas práticas de documentação de forma simples e direta!
🥰 Siga nossa página no Linkedin e no Instagram e ajude a divulgar nosso conteúdo. Por mais mulheres em tech!
Veja também:
O que é uma boa documentação?
Para entender a importância da documentação, pense na compra de um brinquedo complexo desmontado (como um conjunto grande de blocos de montar):
O Código Puro
Seria o equivalente a entregar a caixa cheia de peças misturadas em sacos plásticos sem nenhuma explicação (exige muito tempo de quem vai montar para adivinhar a ordem de encaixe).
Os Comentários ruins no código
Seria colar pequenos bilhetes em cada pecinha individual dizendo “isso é um bloco azul de plástico” (redundante e poluído).
Uma Boa Documentação (“O Manual do Usuário”)
É o folheto ilustrado que vem na caixa mostrando o desenho do brinquedo montado, a lista de peças organizadas, o passo a passo de montagem rápida e como resolver problemas de encaixe comuns.
Uma boa documentação foca no “porquê” do código existir e em “como usá-lo”, e não em narrar linha por linha o óbvio do que a linguagem já diz.
Três níveis de documentação para seus projetos
Para documentar como uma profissional, divida seus esforços em três frentes:
1. Comentários Úteis (Dentro do arquivo de código)
Evite comentar o óbvio. Foque em explicar o motivo de decisões estranhas de código:
Ruim (Redundante):
# Adiciona 1 ao valor de x
x = x + 1Bom (Explica o motivo):
# Adicionamos 1 para compensar o índice 0 da lista que vem da API externa
x = x + 12. Docstrings (Manual das suas funções)
Docstrings são strings de texto especiais que você escreve no início de funções e classes para explicar o que elas esperam receber e o que elas devolvem:
def calcular_desconto(valor_total, cupom):
"""
Calcula o valor final da compra com base em um cupom de desconto.
Parâmetros:
valor_total (float): O valor cheio da compra.
cupom (str): O nome do código de desconto (ex: 'DESCONTO10').
Retorna:
float: O valor final calculado com o desconto aplicado.
"""
# Lógica do cálculo...3. README.md (O manual de entrada do repositório)
Foque em criar um arquivo README limpo e estruturado para o GitHub contendo:
O que o projeto faz: Uma breve apresentação didática.
Pré-requisitos: O que é preciso instalar (ex: Python 3.10).
Passo a passo de inicialização: Os comandos para rodar o projeto localmente.
🎁 Receba nossos recursos gratuitos!
Ao assinar nossa newsletter gratuitamente, você terá acesso à nossa biblioteca de recursos, com guias rápidos, e-book, e outros materiais.
👉 https://mulheresprogramando.substack.com/subscribe
Após se inscrever, você receberá um e-mail de boas-vindas com o link para a página de recursos.
Por que aprender a documentar acelera sua carreira em TI?
No mercado profissional, o software é mantido por equipes de desenvolvimento, não por desenvolvedoras solitárias.
Escrever códigos funcionais mas indecifráveis cria gargalos de trabalho em qualquer time.
Candidatas de nível júnior que apresentam repositórios no GitHub com documentações impecáveis, docstrings estruturadas e comentários inteligentes destacam-se de forma brilhante nas seleções.
Isso sinaliza maturidade profissional, facilidade de colaboração e prova aos recrutadores que o seu trabalho está pronto para ser herdado e integrado por outros membros de uma equipe técnica corporativa real.
Conta aqui: Você costuma documentar seus projetos? 💬