DEV Community: 🌈N̸e̸r̸o̷ ̶H̷a̷z̴i̷e̸l̸

Docstrings: Protegendo seu Código da Fada do Esquecimento

🌈N̸e̸r̸o̷ ̶H̷a̷z̴i̷e̸l̸ — Sat, 24 Jan 2026 10:26:17 +0000

Por que utilizar Docstrings? Daqui alguns meses, quando precisar revisitar a função que você escreveu, descobrirá a resposta.

Uma função escrita hoje em dia parecerá óbvia para você, que saberá de cabo a rabo o que ela retorna, como é utilizada e onde. Existe, porém, uma entidade maligna conhecida como "Fada do Esquecimento".

Essa fada surge enquanto dormimos e utiliza uma técnica proibida conhecida como "Mugic" para limpar nosso cérebro, em específico a região do Hipocampo, apagando todas as nossas memórias. Então, somos visitados pela fada e, no dia seguinte, quando vamos mexer no código... Esquecemos o que ele faz.

Infelizmente, não há um jeito de destruir a fada, ela sempre conseguirá deturpar nossas memórias ao longo do tempo. O melhor jeito de lidar com isso é justamente utilizando Docstrings, para documentar no próprio código tudo que nossas funções e métodos recebem, retornam, os erros possíveis e dar exemplos de uso, para que outras pessoas saibam como utilizá-los no código, e no futuro você mesmo possa usar, caso se esqueça.

O que são Docstrings?

Docstrings são, literalmente, Strings. Strings que você utiliza logo após a definição da função ou método para documentá-la. Veja o exemplo abaixo:

def magic_shield(current_mana: int) -> str:
    """
    Um escudo de proteção contra a Fada do Esquecimento.
    Consome 60 de mana e garante que suas memórias serão preservadas por mais um dia.

    Args:
        current_mana (int): Recebe a mana atual. Só é possível utilizar o escudo 
                            de proteção caso a mana seja maior ou igual a 60.

    Raises:
        ValueError: Caso a mana seja inferior a 60.

    Returns:
        str: Retorna o feitiço de invocação do escudo.

    Examples:
        print(magic_shield(80))  # Retorna "Utamo Vita!!!"
        print(magic_shield(40))  # Levanta ValueError

    """
    if current_mana >= 60:
        return "Utamo Vita!!!"

    raise ValueError(f"Mana atual é de {current_mana}. Impossível usar a magia.")

Tão simples que chega a ser ridículo. O tipo de coisa que você escreve em dois minutos e pode poupar horas de análise no futuro. Caso no futuro você esqueça a implementação da função, pode utilizar o comando help() para verificar a Docstring. Veja abaixo:

help(magic_shield)

E a saída será:

Help on function magic_shield in module __main__:

magic_shield(current_mana: int) -> str
    Um escudo de proteção contra a Fada do Esquecimento.
    Consome 60 de mana e garante que suas memórias serão preservadas por mais um dia.

    Args:
        current_mana (int): Recebe a mana atual. Só é possível utilizar o escudo
                            de proteção caso a mana seja maior ou igual a 60.

    Raises:
        ValueError: Caso a mana seja inferior a 60.

    Returns:
        str: Retorna o feitiço de invocação do escudo.

    Examples:
        print(magic_shield(80))  # Retorna "Utamo Vita!!!"
        print(magic_shield(40))  # Levanta ValueError

E caso esteja usando PyCharm, Visual Studio Code ou alguma outra IDE poderosa, Docstrings se tornam AINDA MAIS poderosas, já que você pode posicionar o cursor sobre a função e será exibida uma janela Pop-Up com sua Docstring.

Outros Tópicos dentro de Docstrings

A esmagadora maioria das Docstrings contará com Args, Raises, Examples e Returns. Apesar disso, existem outros tópicos que podem ser encaixados nela. Eles são:

Attributes: Para classes
Yields: Para funções geradoras
Warns: Para avisos
Notes: Para notas importantes
See Also: Para adicionar referências cruzadas
References: Para citações acadêmicas
Deprecated: Para funções obsoletas
Todo: Para indicar funcionalidades futuras
Version: Para controle de versão

Sphinx e Modelos de Docstrings

O padrão utilizado no exemplo mostrado acima foi o padrão Google, porém, existem outros padrões bem utilizados no mercado para que possamos documentar nossas funções com Docstrings. Outro padrão muito comum é o padrão NumPy/SciPy, utilizado geralmente para projetos bem estruturados de dados. Um exemplo pode ser visto abaixo:

def magic_shield(current_mana: int) -> str:
    """
    Um escudo de proteção contra a Fada do Esquecimento.

    Consome 60 de mana e garante que suas memórias serão preservadas por 
    mais um dia.

    Parameters
    ----------
    current_mana : int
        Recebe a mana atual. Só é possível utilizar o escudo de proteção 
        caso a mana seja maior ou igual a 60.

    Returns
    -------
    str
        Retorna o feitiço de invocação do escudo.

    Raises
    ------
    ValueError
        Caso a mana seja inferior a 60.

    Examples
    --------
    >>> magic_shield(80)
    'Utamo Vita!!!'
    >>> magic_shield(40)
    Traceback (most recent call last):
        ...
    ValueError: Mana atual é de 40. Impossível usar a magia.
    """
    if current_mana >= 60:
        return "Utamo Vita!!!"

    raise ValueError(f"Mana atual é de {current_mana}. Impossível usar a magia.")

E temos também o reStruturedText (Apelidado carinhosamente de reST), que é o utilizado em documentações oficiais do Python. Veja a seguir:

def magic_shield(current_mana: int) -> str:
    """
    Um escudo de proteção contra a Fada do Esquecimento.

    Consome 60 de mana e garante que suas memórias serão preservadas por 
    mais um dia.

    :param current_mana: Recebe a mana atual. Só é possível utilizar o 
        escudo de proteção caso a mana seja maior ou igual a 60.
    :type current_mana: int
    :return: Retorna o feitiço de invocação do escudo.
    :rtype: str
    :raises ValueError: Caso a mana seja inferior a 60.

    .. rubric:: Examples

    >>> magic_shield(80)
    'Utamo Vita!!!'
    """
    if current_mana >= 60:
        return "Utamo Vita!!!"

    raise ValueError(f"Mana atual é de {current_mana}. Impossível usar a magia.")

Todos são válidos e funcionais. Qual você deve usar depende puramente de convenções ou se alguém definiu que deve ser assim. Ademais... o reST é o padrão ouro para ser utilizado com Sphinx, mas hoje em dia qualquer formato de Docstring funciona caso utiliza a extensão oficial sphinx.ext.napoleon. Por isso, dica da tia: Utilize o padrão que te deixa mais confortável, salvo se houver alguma convenção definida pela equipe.

Mas o que é Sphinx?

Sphinx é uma poderosa ferramenta que transforma todas as suas Docstrings em código HTML. Você pode instalá-la utilizando pip install sphinx e ao rodar sphinx-quickstart no console, o Sphinx irá criar todos os arquivos de configuração necessários.

Escreva suas Docstrings e códigos normalmente. Quando quiser documentar, basta utilizar sphinx-apidoc -o source . e make html no terminal e o Sphinx lerá TUDO que foi feito e criará um site bonitinho com sua documentação.

Veja o site oficial do Python: 3.14.2 Documentation

Ele foi completamente feito com Sphinx.

Lindo, não?

Dica de Platina

Ao utilizar sphinx-quickstart no terminal, verá que surgirão novas pastas e arquivos. Eles são os arquivos para configurar o Sphinx. Procure pelo arquivo conf.py e encontrará algo parecido com isso:

extensions = []

Modifique, adicionando esse bloco de código:

import os
import sys

sys.path.insert(0, os.path.abspath('..'))

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    'sphinx.ext.viewcode',
]
napoleon_google_docstring = True
# napoleon_numpy_docstring = True

Agora ele será capaz de ler Docstrings automaticamente, mostrará o código fonte e suportará outros formatos além do reST.

Note também que a linha napoleon_numpy_docstring = True está comentada. Caso esteja utilizando o modelo de documentação do NumPy, utilize ela, caso esteja utilizando o do Google, utilize napoleon_google_docstring = True.
A importação das bibliotecas e definição do Path servem para que o Sphinx leia onde estão seus códigos. o '..' indica que os códigos estão uma pasta acima, mas caso estejam dentro de uma pasta específica, você deve modificar para que o Path corresponda à localização de seus códigos.

Dica de Diamante

O comando make html só é funcional em ambientes baseados em Unix, logo, dificilmente funcionará no Windows. Apesar disso, note que o Sphinx gerou um arquivo chamado make.bat. Execute-o no console com .\make.bat html e assim terá o Sphinx rodando no Windows.

No Linux é sempre mais fácil... Já pensou em migrar?

Fluxo completo de Documentação

Caso tenha se perdido, aqui um guia completo para gerar sua documentação via Sphinx.

# 1. Instalar
pip install sphinx

# 2. Configurar
sphinx-quickstart # Responda as perguntas que surgirão, como nome, data, etc.

# 3. Configurar conf.py

# 4. Gerar documentação
sphinx-apidoc -o source .   # Gera arquivos .rst
make html                   # No Linux e Mac
.\make.bat html             # No Windows

# 5. Abrir
open build/html/index.html  # No Mac
start build/html/index.html # No Windows
xdg-open build/html/index.html  # No Linux

Sempre documente seus códigos! Eles são sua proteção contra a Fada do Esquecimento e um sinal elevado de maturidade computacional.

Closures em Python

🌈N̸e̸r̸o̷ ̶H̷a̷z̴i̷e̸l̸ — Thu, 15 Jan 2026 07:08:09 +0000

Quais nomes na história não precisam ser nomeados para serem lembrados?
Pense nos indivíduos MAIS FAMOSOS E INFLUENTES NA HISTÓRIA DA CIVILIZAÇÃO HUMANA. Talvez você recorde de nomes como Jesus Cristo de Nazaré, Caio Júlio César, Michael Jackson, Albert Einstein, Sir Isaac Newton, Wolfgang Amadeus Mozart, Eu (Em algum momento no futuro)... pois bem, arquétipos que, para o bem ou para o mal, marcaram seu nome na história. Suas lendas estão marcadas no consciente coletivo da humanidade, tornando-se símbolos que não precisam ser nomeados.

Em Python, temos algo parecido: Closures. Funções que se recordam de variáveis externas, mesmo que essas variáveis não sejam passadas como parâmetros nas funções quando chamadas.

— De onde vem esse valor?
— Você sabe.
— Sei? — pergunta a Função, confusa.
— Sabe...

Mas, então, como seria a construção de uma Closure no código?
Algo parecido com isso:

def salutation(praise: str):
    def genius(name: str):
        return f"{praise} {name}!"
    return genius

praiser = salutation("Olá")

print(praiser("Mozart"))
print(praiser("Newton"))

Explicação do Código

Caso tenha copiado o código e executado, notará que a saída foi

Olá Mozart!
Olá Newton!

Mas o único parâmetro passado dentro do print() foram as strings "Mozart" e "Newton". A função se recordou do valor definido para salutation() definido anteriormente, mesmo que o escopo já tenha finalizado sua execução.

E adentrando as bases da Closure... Temos aqui uma função dentro de uma função, um conceito conhecido como "Função Aninhada".

def salutation(praise: str):
    def genius(name: str):
        return f"{praise} {name}!"
    return genius

Note que a função salutation(), que está no lado externo, retorna a própria função genius(), no lado interno. Ela também recebe um parâmetro praise: str. Uma string que, para nosso exemplo, carregará uma saudação como "Olá".
A função genius(), por sua vez, executa a lógica e retorna uma string formatada com praise: str, que é passada como parâmetro na função externa, e name: str, que é passada como parâmetro na função genius().

E agora... magia!

praiser = salutation("Olá")

Invocamos uma variável que será usada de forma intermediária. Ela carregará consigo o retorno da função salutation(), genius(), mas definimos aqui o parâmetro que será recebido por praise: str.

E façamos um teste aqui... Copie as linhas de código abaixo e cole em algum lugar para executar:

print(praiser.__closure__)
print(praiser.__closure__[0].cell_contents)

Mesmo após termos terminado de executar a função salutation(), o parâmetro que passamos continua lá! Ele foi para um lugar mágico, de sonhos e esperanças — algo próximo de Valhalla —, onde os parâmetros permanecem lembrados mesmo após o fim da execução da função.
Por isso, quando executamos as linhas abaixo

print(praiser("Mozart"))
print(praiser("Newton"))

Invocamos as funções com a variável intermediária praiser(), que está armazenando a função genius() — já que genius() é o retorno de salutation(), e invocamos ela ao definirmos praiser() — e definimos o parâmetro como o nome de quem será saudado.
O parâmetro de salutation() foi lembrado!
E o melhor de tudo, você pode criar variações da mesma função! Confira no código abaixo:

def salutation(praise: str):
    def genius(name: str):
        return f"{praise} {name}!"
    return genius

praiser = salutation("Olá")
imperial_praiser = salutation("Hail")
roman_praiser = salutation("Ave")

print(praiser("Mozart"))
print(praiser("Newton"))
print(imperial_praiser("Sithis"))
print(imperial_praiser("the Empire"))
print(roman_praiser("César"))

A saída será:

Olá Mozart!
Olá Newton!
Hail Sithis!
Hail the Empire!
Ave César!

E caso não queira criar uma nova variável para tal, é possível usar na mesma linha:

print(salutation("Saudações")("Terráqueos"))

E a saída ficará:

Saudações Terráqueos!

Nosso exemplo é apenas uma saudação besta, para fins didáticos, então talvez você ainda não esteja vendo uma utilidade prática para Closures. Vamos ver agora um exemplo realmente bom, que ilustre a utilidade titânica dessa funcionalidade do Python.

Exemplo TITÂNICO

Conhece a biblioteca Pandas?
Pandas é uma biblioteca utilizada para manipular Datasets, ler conjuntos de dados, organizar planilhas, etc. Seu nome é derivado de "Panel Data", que é um termo amplamente utilizado em estatística, econometria e áreas correlatas.

A biblioteca Pandas não tem nada a ver com Kung-Fu... Mas seria legal se tivesse!

Para nosso exemplo a seguir, irei assumir que sabe minimamente utilizar o Pandas.

Veja o código abaixo:

import pandas as pd

def remove_lines(*args, mode='individual'):
    def transform_df(df):
        if mode == 'interval' and len(args) == 1:
            return df.drop(list(range(0, args[0])))
        elif mode == 'interval' and len(args) == 2:
            return df.drop(list(range(args[0],args[1])))
        else:
            return df.drop(list(args))
    return transform_df
    
def remove_columns(*args, mode='individual'):
    def transform_df(df):
        if mode == 'interval' and len(args) == 1:
            return df.drop(df.columns[0:args[0]], axis=1)
        elif mode == 'interval' and len(args) == 2:
            return df.drop(df.columns[args[0]:args[1]], axis=1)
        else:
            return df.drop(df.columns[list(args)], axis=1)
    return transform_df

def rename_columns(*args):
    def transform_df(df):
        return df.set_axis(list(args), axis=1)
    return transform_df

Nesse código estamos definindo 3 funções diferentes — 3 closures — para manipular estruturas em Pandas. A primeira função remove linhas, a segunda remove colunas e a terceira renomeia as colunas. Vamos analisar cada função individualmente, isso também será um belo salto para entendermos melhor o Pandas.

def rename_columns(*args):
    def transform_df(df):
        return df.set_axis(list(args), axis=1)
    return transform_df

Analisando o código acima, podemos ver que a função externa recebe *args. Ele é como um "parâmetro coringa". Ao inserir *args onde se inserem os parâmetros na hora de criar uma função, você está dizendo que a função pode receber uma quantidade indeterminada de parâmetros — podendo ser 1 parâmetro, 2 parâmetros, 10 parâmetros ou +8000 parâmetros.
Já a função interna recebe um dataframe do Pandas. A lógica da função interna consiste em renomear as colunas do dataframe com os nomes que forem passados como parâmetro na função externa.

Já a função para remover linhas...

def remove_lines(*args, mode='individual'):
    def transform_df(df):
        if mode == 'interval' and len(args) == 1:
            return df.drop(list(range(0, args[0])))
        elif mode == 'interval' and len(args) == 2:
            return df.drop(list(range(args[0],args[1])))
        else:
            return df.drop(list(args))
    return transform_df

Ela também recebe *args, com o adendo de receber mode. mode já vem com um valor padrão, individual, isso indica que, caso nenhum valor seja passado, o valor será individual.
Logo, seguimos para a função interna que também recebe um dataframe e prossegue para a lógica de remoção de linhas.

Já a última função, para remover colunas, é praticamente idêntica à de remover linhas, com o único adendo de indicar que se trata de colunas, não de linhas.

def remove_columns(*args, mode='individual'):
    def transform_df(df):
        if mode == 'interval' and len(args) == 1:
            return df.drop(df.columns[0:args[0]], axis=1)
        elif mode == 'interval' and len(args) == 2:
            return df.drop(df.columns[args[0]:args[1]], axis=1)
        else:
            return df.drop(df.columns[list(args)], axis=1)
    return transform_df

E por que essas 3 closures são úteis?

Se fossem apenas funções, o trabalho para implementá-las aumentaria bastante. Como são closures, podemos facilmente utilizá-las através do pipe().

transformed_df = (df.pipe(remove_lines(0, 2, mode='interval'))
                .pipe(remove_columns(2))
                .pipe(rename_columns('AA', 'SQ')) )

Não há adjetivo melhor para definir isso do que ELEGANTE!
A utilização de closures nos permitiu utilizar funções em cadeia com pipe(), funcionando exatamente como uma linha de montagem, onde cada resultado de função é passado como parâmetro para a próxima função, em sequência. Além de nos poupar diversas linhas de código, permite dinamismo, melhor legibilidade e manutenção de código.

Pacman e as Instalação de Bibliotecas

🌈N̸e̸r̸o̷ ̶H̷a̷z̴i̷e̸l̸ — Mon, 05 Jan 2026 07:57:13 +0000

Quando se é Noob em R, costumamos importar bibliotecas usando o clássico install.packages("tidyverse") seguido de library(tidyverse) para importá-la no código.
Evoluindo um pouco, descobre-se que validar se a instalação já foi feita é uma boa prática, então passamos a utilizar if(!require(tidyverse)) install.packages("tidyverse"). Eu estava justamente nesse nível... ATÉ HOJE!!!

Sim, Pacman é o Herói que elevará o nível de nosso R!

Pacman

Você pode (E DEVE!) conferir a documentação do Pacman para R clicando aqui.
Pacman, abreviação de Package Manager, é uma poderosa biblioteca para gerenciar seus pacotes.

Utilizá-lo é muito simples e basta que você o instale corretamente em seu computador através do

if(!require(pacman)) install.packages("pacman")

E eu prometo, será a última vez que utilizará esse mesmo comando! A partir de hoje poderá instalar e importar todos os seus pacotes utilizando

pacman::p_load()

O Pacman possui diversos outros comando úteis, dependendo da sua necessidade, mas dificilmente algum fará tanta diferença em sua vida quanto o p_load(). O p_load automaticamente verifica se as bibliotecas estão instaladas e as instala caso não estejam. Por fim, também importa elas no seu código, eliminando qualquer necessidade de verificação, instalação e importação extra. Vejamos o exemplo abaixo:

pacman::p_load(tidyverse, janitor, fs, vroom)

Principalmente caso seu código exija a importação de muitas bibliotecas, o Pacman será de grande ajuda!

Dica de Platina

Existe um arquivo chamado .Rprofile em algum lugar no seu computador. Ele gerencia as configurações iniciais do R. Uma vez o Pacman instalado, adicione o comando abaixo e garanta que o Pacman sempre será inicializado com o R, acabando com a necessidade de executar a linha abaixo toda vez.

if(interactive()) require(pacman)

Caso não encontre o arquivo .Rprofile, utilize o comando abaixo:

if(!require(usethis)) install.packages("usethis")
usethis::edit_r_profile()

Você abrirá o arquivo do .Rprofile no próprio RStudio. Apenas adicione o comando que carrega o Pacman e salve.

Inclusive... Caso esteja trabalhando num projeto compartilhado com alguém, evite instalações automáticas das bibliotecas com o Pacman para garantir que você e seu camarada estejam sempre utilizando as mesmas versões da biblioteca, garantindo que o código sempre funcionará sem erros. Para projetos compartilhados, considere usar o Renv.

Outros comandos úteis do Pacman

Além de caçar fantasmas e instalar e importar bibliotecas automaticamente, Pacman também nos ajuda em outras coisas úteis. Caso não coloque nomes de bibliotecas dentro dos parâmetros, então os comandos afetarão TODAS as bibliotecas do seu ambiente de desenvolvimento.

Atualizar Bibliotecas

Através do comando abaixo, o Pacman atualiza automaticamente todas as bibliotecas instaladas.

p_update()

Descarregar Bibliotecas

O comando abaixo nos permite descarregar as bibliotecas de nosso código, liberando memória ou eliminando bugs por bibliotecas defeituosas ou em conflito.

p_unload()

Instalar Bibliotecas Temporariamente

Só precisa usar determinada biblioteca por certo tempo e não quer instalar ela em todo o seu ambiente? Este comando permite que a biblioteca seja instalada e automaticamente apagada quando a sessão do R foi encerrada.

p_temp()

Conferir os autores de uma biblioteca

Caso queira saber quem foram os criadores de determinada biblioteca, use este código para prestar suas continências.

p_author()

Dica de Diamante

Utilize os comandos do Pacman utilizando pacman:: antes do método específico. "::" é um operador chamado "Operador de Namespace". Ele nos permite utilizar atributos e métodos de alguma biblioteca sem precisarmos importar ela com library(). Ao utilizar pacman::p_update(), por exemplo, estamos dizendo ao R para executar o comando p_update() da biblioteca pacman, mas sem importá-la toda no código.
Além do mais, o operador de namespace é especialmente útil quando existem duas bibliotecas que utilizam funções diferentes com o mesmo nome.