Python/Conceitos básicos/Comentários e docstrings

Há em todas as linguagens de programação a necessidade de documentar uma linha ou um bloco de código para documentar o que serve aquele bloco de código. Em Python comentários são iniciados com #, tudo que estiver depois do # será ignorado pelo interpretador, portanto considerado como comentários, o fechamento do comentário acaba quando acabar a linha do interpretador.

As docstrings são mais comumente introduzidas no início de uma classe, de uma função ou no início do programa para definir o escopo do software ou o escopo de métodos, seu símbolo padrão são as três aspas duplas ou simples.

Para quem está lendo o código do programa não existe muita diferença (exceto estética) entre comentários e docstrings, mas para o usuário a diferença é marcante, pois uma docstring não ´é ignorada pelo interpretador, mas passa a fazer parte do objeto sobre o qual ela foi definida, podendo ser acessada através do help.

Por exemplo, entre com as linhas abaixo. Note que o arquivo não contém nenhum caracter fora do conjunto ASCII padrão (usar acentos pode dar problema no Windows):

#
# Comentários:
#

def fat1(n):
#   Entre com fat1(n) para calcular o fatorial de n
#   Exemplo: fat1(5)
    if (n <= 1):
       return 1
    return n * fat1(n-1)

#
# Docstrings:
#

def fat2(n):
    '''
    Entre com fat2(n) para calcular o fatorial de n
    Exemplo: fat2(5)
    '''
    if (n <= 1):
       return 1
    return n * fat1(n-1)

Após carregar as linhas, vamos fazer alguns testes:

>>> fat1(3)
>>> fat2(3)

Note que, se você escreveu as linhas anteriores em um programa, por exemplo, fatorial.py, e incluiu o programa usando "import fatorial", então é preciso chamar funções através de fatorial.fat1(3) e fatorial.fat2(3), respectivamente.

Para ver como funciona a docstring, entre agora com:

>>> help(fat1)
>>> help(fat2)

Note que não existe documentação para fat1, mas fat2 tem a documentação escrita na docstring.