Space4Makers

Space4Makers

Python docstrings

Python docstrings

Uma forma embutida de escrever documentações

Gabriel Fonseca's photo
Gabriel Fonseca
·Jun 21, 2021·

3 min read

Subscribe to my newsletter and never miss my upcoming articles

O que é docstring?

Docstring é uma forma embutida de documentação de classes, funções, módulos, etc, encontrado em Python, nos ajuda a descrever algo de uma maneira eficiente sem precisar poluir o código com comentários, deixando esses mais específicos como: todo, fixme, etc ...

Padrão do Google

A forma de implementar docstrings com que eu mais me identifiquei e recomendo é a do google, google docstring, fica realmente clean e bem objetivo, porém eu realizo algumas modificações na forma default

class GoogleDocstring:
    """
    google dosctring implementation example

    Attributes:
        - language (str): The knowledge programming language
        - version (float): Version of the informed programming language
        - open_source (bool): Describe if the informed programming language is open source

    Methods:
        - lorem_ipsum: Return a lorem ipsum string to stdout
        - good_morning: Display a good morning string for stdout, if the time is between 07:00 am and 11:59 am

    Exceptions:
        - InvalidTime: Happens when the current time is not between a valid time

    Business Rules:
        - Need to print "good morning" only if the current time is between 07:00 am and 11:59 am

    Other Sections:
    Here we can put others compatibles sections like:
        - Filters: If this abstraction can be filtered
        - TODO: Todo items
        - Note: Implement notes for the client
        - Others from your preference, be creative ...
    """

    # Implementation after one empty line from docstring
    ...

Porque utilizar docstrings e não comentários?

Comentários não são interpretados pelo Python como as docstrings são, quando declaramos uma docstring em uma função

def lorem_ipsum() -> None:
    """Display 'lorem ipsum' to stdout"""
    ...

caso haja algum tipo de dúvida sobre o funcionamento da mesma, além claro de inspecionar o código fonte, podemos simplesmente realizar um print da documentação dessa função

print(lorem_ipsum.__doc__)

# Execution

>>> Display 'lorem ipsum' to stdout

DICA: Podemos também utlizar a função help passando a função lorem_ipsum como argumento

Aonde implementar

Implementar docstrings em todos os lugares pode ser muito chato e sabemos que nem sempre temos tempo o suficiente de implementar a documentação em todos os softwares que produzimos, então na minha opinião deveríamos implementar docstrings em 2 (dois) momentos:

  • Quando há o envolvimento de regras de negócios

Quando temos uma função, método ou classe que implementa alguma regra de negócio, é válido implementar docstrings pois assim outros devs que for realizar a manutenção da base de código que implementamos estará ciente que naquele local específico deve se ter uma atenção maior pois se implementa alguma regra de negócio

  • Quando o seu código está complexo

Código complexo - se está complexo pode ser um bom sinal para se refatorar e tentar deixar mais simples - pode causar muitas "dúvidas" em colaboradores menos experientes, e até mesmo nos mais experientes, esse é um outro bom momento para se utilizar das dosctrings para se contextualizar sobre a implementação realizada

Uso em scripts

Scripts de uso rápido nem sempre vale o esforço de implementar uma documentação, porém se esse script tiver um uso mais considerável isso se paga ao passar do tempo, segue um exemplo de documentação de script tendo como base o livro Shell Script Profissional - Aurelio Marinho Jargas

"""
#!/usr/bin/env python

battery_notifier.py - Display the current battery status from a GNU/Linux system

Author: Bart Simpsons <bart@mail.com>

-------

This script display in STDOUT the battery status, only works on a GNU/Linux system, 
for more instructions run with '-h' argument

Usage:
    $ ./battery_notifier.py
    or
    $ python battery_notifier.py

-------

History:
    v1.0.0 2021-01-01, Bart Simpsons:
        - Initial version
    v1.0.1 2021-02-15, Bart Simpsons:
        - Added pretty output actions

License: MIT
"""

...

eaí, vocês costumam utilizar dosctrings em códigos de produção? Discorda de algum ponto citado?


"Manifestamos em público aquilo que fizemos durante anos em um quartinho esquecido"

"Alessandro Vilas Boas"

 
Share this