Como documentar código em Python

Se você está começando em Python e quer aprender mais, faça o curso Intermediate Python da DataCamp.

A importância de documentar seu projeto

Documentação é parte essencial de qualquer projeto em que você trabalhe, independentemente da linguagem de programação. Um projeto com várias APIs em produção, usado por muitos usuários, mas sem documentação, está incompleto. Pense como desenvolvedor: como você se sentiria tentando replicar um projeto ou usar parte dele sem nenhuma documentação? Integrar isso à sua arquitetura seria, no mínimo, trabalhoso.

Uma boa documentação aumenta as chances de sucesso do seu projeto, porque, quando você o compartilha com o mundo, quer que as pessoas usem — ainda mais se for open source. Você também vai querer que a comunidade contribua e o torne melhor.

O renomado criador da linguagem Python costuma dizer que código é lido com muito mais frequência do que é escrito. Essa frase destaca a importância da documentação para que seu código ou projeto seja compreendido e implementado por outras pessoas.

Imagine que você trabalha na empresa XYZ, está cumprindo o aviso prévio e seu gestor pede para transferir o projeto a um colega. Você pode fazer um KT (knowledge transfer), mas e se seu colega não conseguir executar um dos códigos com sucesso? Há várias razões possíveis: talvez os binários necessários não combinem com os do sistema operacional atual, por exemplo.

O que exatamente é documentação?

Documentação tem vários componentes. Para ser considerada adequada, ela precisa ser bem estruturada em torno desses componentes e segui-los.

Em alto nível, os componentes são:

• Garantir que o codebase do projeto esteja bem comentado.

• Seguir os padrões de codificação do PEP 8 do Python.

• Tutoriais concretos sobre como o projeto foi construído, especialmente quando é um projeto open source com foco em aprendizado.

• Um guia de instalação dos pacotes e módulos necessários para construir o software, além de uma ficha técnica se o projeto incluir hardware. Por exemplo, como instalar Anaconda, TensorFlow, Keras etc.

• Registros de discussões sobre o andamento do projeto a cada etapa, que tenham contribuído para a implementação bem-sucedida do software.

• Material de referência com a descrição técnica do stack de tecnologia usado durante o desenvolvimento.

• O desenho arquitetural do projeto ou da solução de software.

Esses pontos são apenas alguns dos componentes que podem existir em um documento bem estruturado e completo. É importante mantê-los distintos, o que também facilita a manutenção futura da documentação.

Um exemplo de documentação abrangente, com boa parte dos componentes que discutimos, seria algo como o mostrado abaixo:

Muita gente confunde comentar e documentar e considera que são a mesma coisa. Comentários descrevem seu código para o usuário, para quem faz manutenção e até para você mesmx como referência futura. Comentários atuam apenas no nível do código e podem ser considerados um subconjunto da documentação. Comentários ajudam o leitor a:

• entender seu código,
• torná-lo autoexplicativo, e
• compreender seu propósito e design.

Lembre-se: como o Python segue o PEP 8, até os comentários devem obedecer a esses padrões. A documentação oficial do Python recomenda que, em blocos longos de texto com menos restrições estruturais (docstrings ou comentários), o comprimento da linha seja limitado a 72 caracteres.

Para verificar se seu código segue o PEP 8, você pode usar o módulo pylint do Python. Com ele, dá para ajustar o limite de caracteres de comentários e de quaisquer outras linhas de código.

Vamos ver alguns exemplos.

• Descrição de importação de módulo

import tensorflow as tf
#imports tensorflow as tf. Tensorflow is an n-dimensional matrix.
#just like a 1-D vector, 2-D array, 3-D array etc.

• Descrição de definição de variável

n_classes = 10 # MNIST total classes (0-9 digits)

Para um entendimento mais profundo sobre comentários e seus prós e contras, confira este post útil.

Agora vamos ver como docstrings ajudam a documentar o codebase do seu projeto.

Docstrings para documentar código em Python

Docstring em Python é uma string literal de documentação que aparece na definição de uma classe, módulo, função ou método, escrita como a primeira instrução. Docstrings ficam acessíveis pelo atributo (__doc__) de qualquer objeto Python e também pela função embutida help().

Docstrings são ótimas para entender a funcionalidade da parte maior do código, isto é, o propósito geral de uma classe, módulo ou função. Já os comentários são usados em trechos, instruções e expressões, que tendem a ser menores. São textos descritivos escritos pelo programador principalmente para si, para lembrar o que cada linha ou expressão faz, e também para quem deseja contribuir com o projeto. Documentar seu código é essencial para escrever código limpo e programas bem estruturados. Apesar disso, não há regras rígidas para fazê-lo.

Há duas formas de escrever docstrings: docstrings de uma linha e docstrings multilinha. São os formatos que cientistas de dados e programadores usam em seus projetos.

• As docstrings de uma linha cabem inteiras em uma única linha. Você pode usar aspas triplas simples ou duplas; as de abertura e fechamento precisam coincidir. Em docstrings de uma linha, as aspas de fechamento ficam na mesma linha das de abertura. A convenção mais comum é usar aspas triplas duplas.

def square(a):
    '''Returned argument a is squared.'''
    return a**a

print (square.__doc__)


help(square)

Returned argument a is squared.
Help on function square in module __main__:

square(a)
    Returned argument a is squared.

• Docstrings multilinha trazem a mesma linha inicial das de uma linha, seguida por uma linha em branco e então o texto descritivo.

def some_function(argument1):
    """Summary or Description of the Function

    Parameters:
    argument1 (int): Description of arg1

    Returns:
    int:Returning value

   """

    return argument1

print(some_function.__doc__)

Summary or Description of the Function

    Parameters:
    argument1 (int): Description of arg1

    Returns:
    int:Returning value

A partir da tabela acima, vamos escolher o Pydoc como um dos formatos de docstring e explorá-lo um pouco.

Como você viu, docstrings podem ser acessadas pelo atributo __doc__ e pela função help(). Você também pode usar o módulo embutido Pydoc, que é bem diferente em recursos e funcionalidades quando comparado ao atributo doc e à função help.

Pydoc é uma ferramenta útil quando você quer compartilhar o código com colegas ou torná-lo open source, mirando um público muito mais amplo. Ele pode gerar páginas web a partir da documentação do seu Python e também iniciar um servidor web.

Vamos ver como funciona.

A maneira mais simples e prática de executar o módulo Pydoc é rodá-lo como script. Para executá-lo dentro de uma célula do Jupyter Lab, use o caractere de exclamação (!).

!python -m pydoc

pydoc - the Python documentation tool

pydoc <name> ...
    Show text documentation on something.  <name> may be the name of a
    Python keyword, topic, function, module, or package, or a dotted
    reference to a class or function within a module or module in a
    package.  If <name> contains a '\', it is used as the path to a
    Python source file to document. If name is 'keywords', 'topics',
    or 'modules', a listing of these things is displayed.

pydoc -k <keyword>
    Search for a keyword in the synopsis lines of all available modules.

pydoc -n <hostname>
    Start an HTTP server with the given hostname (default: localhost).

pydoc -p <port>
    Start an HTTP server on the given port on the local machine.  Port
    number 0 can be used to get an arbitrary unused port.

pydoc -b
    Start an HTTP server on an arbitrary unused port and open a Web browser
    to interactively browse documentation.  This option can be used in
    combination with -n and/or -p.

pydoc -w <name> ...
    Write out the HTML documentation for a module to a file in the current
    directory.  If <name> contains a '\', it is treated as a filename; if
    it names a directory, documentation is written for all the contents.

Observando a saída acima, o primeiro uso do Pydoc é exibir documentação em texto de uma função, módulo, classe etc. Vamos ver como aproveitar isso melhor do que com a função help.

!python -m pydoc glob

Help on module glob:

NAME
    glob - Filename globbing utility.

MODULE REFERENCE
    https://docs.python.org/3.7/library/glob

    The following documentation is automatically generated from the Python
    source files.  It may be incomplete, incorrect or include features that
    are considered implementation detail and may vary between Python
    implementations.  When in doubt, consult the module reference at the
    location listed above.

FUNCTIONS
    escape(pathname)
        Escape all special characters.

    glob(pathname, *, recursive=False)
        Return a list of paths matching a pathname pattern.

        The pattern may contain simple shell-style wildcards a la
        fnmatch. However, unlike fnmatch, filenames starting with a
        dot are special cases that are not matched by '*' and '?'
        patterns.

        If recursive is true, the pattern '**' will match any files and
        zero or more directories and subdirectories.

    iglob(pathname, *, recursive=False)
        Return an iterator which yields the paths matching a pathname pattern.

        The pattern may contain simple shell-style wildcards a la
        fnmatch. However, unlike fnmatch, filenames starting with a
        dot are special cases that are not matched by '*' and '?'
        patterns.

        If recursive is true, the pattern '**' will match any files and
        zero or more directories and subdirectories.

DATA
    __all__ = ['glob', 'iglob', 'escape']

FILE
    c:\users\hda3kor\.conda\envs\test\lib\glob.py

Agora, vamos extrair a documentação de glob usando a função help.

help(glob)

---------------------------------------------------------------------------

NameError                                 Traceback (most recent call last)

<ipython-input-13-6f504109e3a2> in <module>
----> 1 help(glob)


NameError: name 'glob' is not defined

Como você vê, ocorre um NameError porque glob não está definido. Para usar a função help e extrair a documentação, você precisa primeiro importar o módulo — o que não é necessário com o Pydoc.

Vamos explorar o recurso mais interessante do módulo Pydoc: rodá-lo como um serviço web.

Para isso, basta executar o Pydoc como script com o argumento -b, que inicia um servidor HTTP em uma porta livre aleatória e abre o navegador para você navegar interativamente pela documentação. Isso é útil quando há vários serviços rodando e você não lembra qual porta está ociosa.

!python -m pydoc -b

^C

No momento em que você executa a célula acima, uma nova janela é aberta em uma porta aleatória e o navegador fica parecido com o mostrado a seguir.

Vamos ver a documentação do módulo h5py, um formato de arquivo usado para armazenar pesos de arquiteturas de redes neurais.

Essenciais ao documentar projetos em Python

Independentemente do objetivo, visão e propósito, a documentação de todo projeto tende a seguir uma estrutura semelhante. O projeto pode se encaixar nas categorias abaixo:

• Projeto privado (pessoal): pode ser para montar portfólio ou como freelancer mantendo um repositório no GitHub.

• Projetos colaborativos (time): pode ser um projeto na sua organização ou uma competição no Kaggle.

• Projetos open source: focados em compartilhar com um público amplo. Espera-se colaboração, contribuições e manutenção do codebase e da documentação no longo prazo.

Apesar das diferentes visões, um template de documentação pode ser compartilhado entre todos esses tipos.

Suponha que você esteja trabalhando em um projeto open source e precise criar um repositório no GitHub com documentação detalhada e atualizada regularmente. Eis os pontos essenciais para ter em mente:

• Arquivo de requisitos: muitos autores esquecem, mas é crucial. Ajuda usuários a reproduzir seu código rapidamente. Geralmente é um arquivo de texto com todos os pacotes e módulos, com suas respectivas versões, usados no projeto. Os requisitos podem até estar no Readme, mas tê-los separados é melhor, pois o usuário pode rodar o arquivo com um comando pip e instalar todas as dependências no sistema.

• Readme: normalmente em Markdown, serve como espinha dorsal de muitos projetos. Traga um resumo do projeto, seus recursos e propósito, de preferência com um logo. Inclua instruções de instalação e uso. Adicione mudanças relevantes desde a versão anterior. Scripts de teste ou um "tour rápido" para executar o código com sucesso direto no Readme dão mais confiança para o usuário seguir adiante. Também pode destacar possíveis problemas que o usuário pode enfrentar.

• Como colaborar: especialmente importante em open source. Deve explicar como novos colaboradores podem contribuir. Isso inclui desenvolver novos recursos, corrigir bugs conhecidos, melhorar a documentação, adicionar testes ou reportar issues. Colaboradores podem até lançar uma v2.0 do mesmo projeto e levá-lo mais longe.

• Licença: um arquivo de texto simples descrevendo a licença do projeto. Fundamental em open source — por exemplo, Boost, Apache, MIT etc. Isso informa se o projeto pode ser usado comercialmente e em que condições.

• Atribuição de tarefas: em projetos compartilhados, como no Kaggle, você pode definir as tarefas de cada membro e o andamento. Isso ajuda a acompanhar o progresso geral.

• Reutilização de framework: vital em projetos como os do Kaggle, em que colegas podem reaproveitar o que você construiu, economizando muito tempo. Por exemplo, pipeline de pré-processamento de dados, script de validação cruzada etc.

Uma documentação altamente recomendada, muito bem estruturada e que é um excelente exemplo de como um projeto open source deve ser, é o repositório do huggingface transformers no GitHub.

Conclusão

Parabéns por concluir o tutorial.

Um bom exercício é explorar mais o módulo Pydoc e outros formatos de docstring do Python, como Epydoc e Google docstrings, e comparar as diferenças.

Fique à vontade para deixar suas dúvidas sobre este tutorial nos comentários abaixo.

Referências:

• Docstrings em Python

Se você está começando em Python e quer aprender mais, faça o curso Intermediate Python da DataCamp.