Resumo : neste tutorial, você aprenderá como adicionar comentários ao seu código. E você aprenderá vários tipos de comentários em Python, incluindo comentários em bloco, comentários embutidos e strings de documentação.
Introdução aos comentários do Python
Às vezes, você deseja documentar o código que escreve. Por exemplo, você pode observar por que um trecho 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 interpreta apenas o código.
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 em 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 em bloco, você começa com um único sinal de hash ( #) seguido por um único espaço e uma string de texto. Por exemplo:
# increase price by 5%
price = price * 1.05Linguagem de código: Python ( python )Comentários embutidos em Python
Ao colocar 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 hash ( #) e é seguido por um espaço e uma sequência de texto.
O exemplo a seguir ilustra um comentário embutido:
salary = salary * 1.02 # increase salary by 2%Linguagem de código: Python ( python )Documentos Python
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 está 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, os docstrings não são os comentários. Eles criam variáveis anônimas que fazem referência às 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) Documentos 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 documentação de uma linha.
O exemplo a seguir ilustra uma docstring de uma linha na quicksort()função:
def quicksort():
""" sort the list using quicksort algorithm """
...Linguagem de código: Python ( python )2) Documentos multilinhas
Ao contrário de uma docstring de uma linha, uma docstring de várias linhas pode abranger várias linhas. Uma docstring multilinha também começa com aspas triplas ( """) e termina com aspas triplas ( """).
O exemplo a seguir mostra como usar docstrings multilinhas:
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%
"""Linguagem de código: Python ( python )Comentários multilinhas em Python
Python não oferece suporte a comentários multilinhas.
No entanto, você pode usar docstrings multilinhas como comentários multilinhas. 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.
Resumo
- Use comentários para documentar seu código quando necessário.
- Um comentário em bloco e um comentário embutido começam com um sinal de cerquilha (
#). - Use docstrings para funções , módulos e classes .
