O segredo de uma documentação simples em Python.

Prontos para mais um diário de bordo? Hoje iremos decorrer sobre docstring, o que é, como é utilizado, por que utilizar e em qual momento deve ser utilizado. A docstring são strings que inserimos no nosso código python, logo se você não é um desenvolvedor Python ou não tem conhecimentos do que é python, tarei um breve resumo sobre.

Python nada mas é que uma linguagem de programação orientada a objetos, segundo kenzie "Python é uma linguagem de programação de alto nível — ou High Level Language —, dinâmica, interpretada, modular, multiplataforma e orientada a objetos — uma forma específica de organizar softwares onde, a grosso modo, os procedimentos estão submetidos às classes, o que possibilita maior controle e estabilidade de códigos para projetos de grandes proporções.".

Bom, agora que sabe mas ou menos o que é Python afinal de contas, vamos falar sobre a docstring. A docstring ela tem como o intuito de explicar o funcionamento de uma classe, método ou função. Ela sempre estará localizada na primeira linha do mesmo, dentro de 3 aspas duplas para abrir e 3 para fechar, olha esse modelo basico.

Neste exemplo acima, criei uma função soma passando dois paramentos e dentro dela, a primeira coisa que eu fiz foi utilizar a docstring pois como eu disse ela tem que está localizada na primeira linha, visto isso fizemos o cálculo e depois retornamos, até este momento nada de estranho, mas se você utilizar a função help() do python, veja o que acontece.

Você executando o arquivo, está será a saída do terminal. Por que utilizar a docstring nos seus projetos? Deixa o código mais limpo, sem a necessidade de tantos comentários para poder explicar o que aquela função ou classe faz. Quando devo utilizar? Simples, isso vai do seu ponto de vista e necessidade, se você acha que aquela função é muito complexa e a nomenclatura dela não esta expressando o que ela faz, você pode sim, utiliza-la, normalmente encontramos mais em projetos de APIs e libs.

Hora da prática, vamos nessa.

Imagine que você está criando um jogo em python, terá que criar os movimentos, a colisão dos objetos, velocidade, entre outros. Enfim, você vai criar muitas classes e funções, isso se você quiser deixar seu código organizado, usando boas práticas. Mas ai você percebeu que certas funções você irá utilizar em outros projetos e pensou em criar uma base, no caso uma lib que faça isso para você sem precisar em criar isso varias vezes, logo você terá que documentar ela toda para que outra pessoa que necessite usa-lá vai saber do que se trata e como usar cada função, classe, método, etc. Você terá que ver onde é que mais vai precisar de atenção de uma explicação detalhada do que faz. Esse é um dos métodos de fazer uma documentação simples, pratica e rápida.

Esse foi uma forma prática de quando você deve utilizar a docstring em seus projetos.

Aqui está o código-fonte utilizando no exemplo:

def _sum(a, b):
    """
    Esta função recebe dois parametros inteiros
    para calcular a soma entre eles.
    :param a: recebe um valor inteiro
    :param b: recebe um valor inteiro
    :return: retorna a soma entre eles
    """

    calc = a + b
    return calc


print(_sum(8, 10))
help(_sum)

Bom, explicado passo a passo sobre docstring, este foi o diário de bordo #02 vamos nos despedindo por aqui. Amanhã voltamos com, mas um diário de bordo.

Este artigo foi útil para você?
Deixe um comentário abaixo.