Resumo: neste tutorial, você aprenderá como adicionar comentários ao seu código. E você aprenderá vários tipos de comentários do Python, incluindo comentários de bloco, comentários embutidos e string de documentação.
Introdução aos comentários do Python
Às vezes, você deseja documentar o código que escreve. Por exemplo, você pode querer observar por que um pedaço de código funciona. Para fazer isso, você usa os comentários.
Normalmente, você usa comentários para explicar fórmulas, algoritmos e lógica de negócios complexa.
Ao executar um programa, o interpretador Python ignora os comentários e apenas interpreta o código.
O Python fornece três tipos de comentários, incluindo comentário em bloco, comentário embutido e string de documentação.
comentários do bloco Python
Um comentário de bloco explica o código que o segue. Normalmente, você recua um comentário de bloco no mesmo nível do bloco de código.
Para criar um comentário de bloco, você começa com um único sinal de cerquilha (#) seguido por um espaço e uma string de texto. Por exemplo:
# aumentar o preço em 5%
price = price * 1.05
Comentários embutidos do Python
Quando você coloca um comentário na mesma linha de uma declaração, você terá um comentário embutido.
Semelhante a um comentário em bloco, um comentário embutido começa com um único sinal de cerquilha (#) e é seguido por um espaço e uma string de texto.
O exemplo a seguir ilustra um comentário embutido:
salary = salary * 1.02 # aumenta salario em 2%
Python docstrings
Uma string de documentação é uma string literal que você coloca como as primeiras linhas em um bloco de código, por exemplo, uma função.
Ao contrário de um comentário normal, uma string de documentação pode ser acessada em tempo de execução usando o obj.__doc__ atributo onde obj é o nome da função.
Normalmente, você usa uma string de documentação para gerar automaticamente a documentação do código.
As strings de documentação são chamadas de docstrings.
Tecnicamente falando, docstrings não são os comentários. Eles criam variáveis anônimas que referenciam as strings. Além disso, eles não são ignorados pelo interpretador Python.
Python fornece dois tipos de docstrings: docstrings de uma linha e docstrings de várias linhas.
1) Docstrings de uma linha
Como o próprio nome indica, uma docstring de uma linha cabe em uma linha. Uma docstring de uma linha começa com aspas triplas (""") e também termina com aspas triplas ("""). Além disso, não haverá nenhuma linha em branco antes ou depois da docstring de uma linha.
O exemplo a seguir ilustra uma docstring de uma linha na função quicksort():
def quicksort():
""" Ordena a lista usando o algoritmo quicksort """
...
2) Documentstrings multi-linha
Ao contrário de uma docstring de uma linha, uma docstring de várias linhas pode abranger várias linhas. Uma docstring de várias linhas também começa com aspas triplas (""") e termina com aspas triplas (""").
O exemplo a seguir mostra como usar docstrings de várias linhas:
def increase(salary, percentage, rating):
""" increase salary base on rating and percentage
rating 1 - 2 no increase
rating 3 - 4 increase 5%
rating 4 - 6 increase 10%
"""
Comentários multilinha do Python
Python não suporta comentários multilinha.
No entanto, você pode usar docstrings de várias linhas como comentários de várias linhas. Guido van Rossum, o criador do Python, também recomendou isso.
É uma boa prática manter seu comentário claro, conciso e explicativo. O objetivo final é economizar tempo e energia para você e outros desenvolvedores que trabalharão no código posteriormente.
