Comentários no código

5.1 Como escrever comentários

No Python, assim como em muitas linguagens de programação, você pode escrever comentários no código. Comentários ajudam programadores e outros membros do projeto a entenderem o código, o que é particularmente útil em trabalho colaborativo e manutenção a longo prazo dos programas. Em Python, existem várias maneiras de adicionar comentários no código.

Comentários de uma linha:

Começam com o símbolo #. Tudo que segue depois do # na mesma linha é ignorado pelo Python. Este tipo de comentário é geralmente usado para observações breves ou explicações de uma linha específica de código. Exemplo:

# Este é um comentário de uma linha
print("Hello, World!") # Explicação da ação da função

Comentários de múltiplas linhas:

No Python, não existe oficialmente uma sintaxe específica para comentários de múltiplas linhas, mas você pode criá-los usando vários comentários de uma linha ou usando aspas triplas, embora este último seja na verdade um literal de string de múltiplas linhas, que não é executado como código. Exemplo:

# Este é um exemplo de comentário de múltiplas linhas
# Cada linha começa com o símbolo #
      

ou:

"""
Este é um literal de múltiplas linhas, que pode ser usado como comentário.
O Python interpreta isso como uma string, mas não faz nada com ela,
se não for atribuída a uma variável ou usada em uma expressão.
"""
    
      

5.2 Por que escrever comentários

Usar comentários no código aumenta sua legibilidade, facilita a manutenção e atualização, além de promover uma colaboração mais eficaz em equipes. Comentários devem ser breves, mas informativos e relevantes, para que sirvam como documentação útil do código sem poluí-lo com informações desnecessárias.

Docstrings:

São strings geralmente localizadas no início de módulos, classes, métodos e funções para descrever seu propósito. Elas são delimitadas por aspas triplas duplas e podem ser usadas para gerar documentação automaticamente.

Exemplo:

def add(a, b):
"""
    Função para somar dois números.
    :param a: primeiro operando
    :param b: segundo operando
    :return: soma de a e b
    """
    return a + b

No mundo da programação, às vezes os desenvolvedores adicionam ao seu código comentários que não só servem como explicações, mas também trazem um sorriso ao rosto. Aqui estão alguns exemplos de comentários engraçados que você pode encontrar no código:

Exemplo 1

 

            # Eu explicaria o que está acontecendo aqui, mas nem eu sei mais.
        

Exemplo 2

 

    # Se isso não funcionar, a culpa é de outra pessoa.

Exemplo 3

 

    # Vim, vi, corrigi... e quebrei.

Exemplo 4

 

    # Quando escrevi isso, somente eu e Deus sabíamos como funciona. 
    # Agora só Deus sabe.

Esses comentários podem adicionar leveza e humor ao processo de desenvolvimento, tornando a base de código menos monótona. Eles também podem servir como um lembrete de que o desenvolvimento de software é um processo criativo e humano.

5.3 Comentar código rapidamente

No PyCharm você pode rapidamente comentar ou descomentar o código usando atalhos de teclado. Para fazer isso, selecione as linhas de código que deseja alterar e pressione Ctrl + / no Windows (ou Cmd + / no macOS). Esta combinação de teclas adiciona ou remove o símbolo de comentário em cada linha selecionada, tornando o processo rápido e eficiente.