Comentários em Python: Guia Completo

# Este é um comentário simples
nome = "Python"  # Comentário ao lado do código
print(f"Olá, {nome}!")  # Isso será executado normalmente

# Este é um comentário de linha única
print("Hello, World!")

# Você pode usar múltiplas linhas
# cada uma com seu próprio #
# para explicações mais longas

idade = 25  # Idade do usuário em anos
preco = 19.99  # Preço em reais com desconto aplicado
ativo = True  # Status do usuário no sistema

# Opção 1: Múltiplas linhas com #
# Este é um comentário
# que ocupa várias linhas
# para explicar algo complexo

"""
Opção 2: String multilinha (não é tecnicamente um comentário)
Mas pode ser usada como comentário
quando não está atribuída a uma variável
"""

'''
Opção 3: Aspas simples triplas
Também funciona da mesma forma
que as aspas duplas triplas
'''

def calcular_imc(peso, altura):
    """
    Calcula o Índice de Massa Corporal (IMC).
    
    Args:
        peso (float): Peso em quilogramas
        altura (float): Altura em metros
    
    Returns:
        float: Valor do IMC calculado
        
    Examples:
        >>> calcular_imc(70, 1.75)
        22.86
    """
    return peso / (altura ** 2)

# Acessando a docstring
print(calcular_imc.__doc__)

# Estilo Google
def somar(a, b):
    """Soma dois números.
    
    Args:
        a (int): Primeiro número
        b (int): Segundo número
        
    Returns:
        int: A soma dos dois números
    """
    return a + b

# Estilo NumPy
def multiplicar(a, b):
    """
    Multiplica dois números.
    
    Parameters
    ----------
    a : int
        Primeiro número
    b : int
        Segundo número
        
    Returns
    -------
    int
        O produto dos dois números
    """
    return a * b

# Estilo Sphinx
def dividir(a, b):
    """
    Divide dois números.
    
    :param a: Primeiro número
    :type a: float
    :param b: Segundo número
    :type b: float
    :returns: Resultado da divisão
    :rtype: float
    :raises ZeroDivisionError: Se b for zero
    """
    if b == 0:
        raise ZeroDivisionError("Divisão por zero não é permitida")
    return a / b

# Aplicando algoritmo de ordenação bubble sort
for i in range(len(lista)):
    for j in range(0, len(lista) - i - 1):
        # Troca elementos se estiverem na ordem errada
        if lista[j] > lista[j + 1]:
            lista[j], lista[j + 1] = lista[j + 1], lista[j]

# Taxa de desconto progressiva baseada no valor da compra
if valor_compra > 1000:
    desconto = 0.15  # 15% para compras acima de R$ 1000
elif valor_compra > 500:
    desconto = 0.10  # 10% para compras entre R$ 500-1000
else:
    desconto = 0.05  # 5% para compras até R$ 500

def calcular_juros_compostos(principal, taxa, tempo):
    """
    Calcula juros compostos usando a fórmula:
    M = P(1 + i)^n
    Onde: M=montante, P=principal, i=taxa, n=tempo
    """
    # Conversão da taxa percentual para decimal
    taxa_decimal = taxa / 100
    
    # Aplicação da fórmula de juros compostos
    montante = principal * (1 + taxa_decimal) ** tempo
    
    return montante

# TODO: Implementar validação de email
def cadastrar_usuario(nome, email):
    # FIXME: Verificar se email já existe no banco
    usuario = {
        'nome': nome,
        'email': email,
        'ativo': True
    }
    return usuario

# HACK: Solução temporária até refatoração da API
# XXX: Este código precisa ser revisado

# ❌ Ruim - obvio demais
x = x + 1  # Incrementa x em 1

# ✅ Bom - explica o propósito
x = x + 1  # Move para próxima posição no array

# ❌ Ruim - muito verboso
# Esta função vai receber dois parâmetros que são números
# e vai retornar a soma desses dois números para o usuário
def somar(a, b):
    return a + b

# ✅ Bom - conciso e informativo
def somar(a, b):
    """Retorna a soma de dois números."""
    return a + b

# ❌ Ruim - comentário desatualizado
def calcular_desconto(valor):
    """Aplica desconto de 10% sobre o valor."""  # Mentira! Agora é 15%
    return valor * 0.85

# ✅ Bom - comentário sempre atual
def calcular_desconto(valor):
    """Aplica desconto de 15% sobre o valor."""
    return valor * 0.85

# ❌ Ruim - explica o que já é óbvio
lista.sort()  # Ordena a lista

# ✅ Bom - explica por que está sendo feito
lista.sort()  # Ordenação necessária para busca binária ser eficiente

def validar_cpf(cpf):
    """
    Valida um número de CPF brasileiro.
    
    Args:
        cpf (str): CPF com ou sem formatação
        
    Returns:
        bool: True se válido, False caso contrário
    """
    # Remove caracteres especiais (pontos e hífen)
    cpf_numeros = ''.join(filter(str.isdigit, cpf))
    
    # CPF deve ter exatamente 11 dígitos
    if len(cpf_numeros) != 11:
        return False
    
    # Verifica se todos os dígitos são iguais (CPF inválido)
    if cpf_numeros == cpf_numeros[0] * 11:
        return False
    
    # Cálculo do primeiro dígito verificador
    soma = sum(int(cpf_numeros[i]) * (10 - i) for i in range(9))
    primeiro_digito = (soma * 10) % 11
    if primeiro_digito == 10:
        primeiro_digito = 0
    
    # Cálculo do segundo dígito verificador
    soma = sum(int(cpf_numeros[i]) * (11 - i) for i in range(10))
    segundo_digito = (soma * 10) % 11
    if segundo_digito == 10:
        segundo_digito = 0
    
    # Verifica se os dígitos calculados coincidem
    return (primeiro_digito == int(cpf_numeros[9]) and 
            segundo_digito == int(cpf_numeros[10]))

# Teste da função
cpf_teste = "123.456.789-09"
print(f"CPF {cpf_teste} é válido: {validar_cpf(cpf_teste)}")

def calcular_salario_liquido(salario_bruto, dependentes=0):
    """
    Calcula o salário líquido com base nas deduções legais.
    
    Args:
        salario_bruto (float): Salário bruto mensal
        dependentes (int): Número de dependentes
        
    Returns:
        dict: Detalhamento do cálculo com valores
    """
    # Cálculo do INSS (2023)
    if salario_bruto <= 1302.00:
        inss = salario_bruto * 0.075  # 7.5%
    elif salario_bruto <= 2571.29:
        inss = salario_bruto * 0.09   # 9%
    elif salario_bruto <= 3856.94:
        inss = salario_bruto * 0.12   # 12%
    else:
        inss = salario_bruto * 0.14   # 14% até o teto
        
    # Limita INSS ao teto máximo
    inss = min(inss, 713.10)
    
    # Base de cálculo para IR (após INSS)
    base_ir = salario_bruto - inss
    
    # Dedução por dependente
    deducao_dependentes = dependentes * 189.59
    base_ir_final = base_ir - deducao_dependentes
    
    # Cálculo do Imposto de Renda (2023)
    if base_ir_final <= 1903.98:
        ir = 0  # Isento
    elif base_ir_final <= 2826.65:
        ir = base_ir_final * 0.075 - 142.80  # 7.5%
    elif base_ir_final <= 3751.05:
        ir = base_ir_final * 0.15 - 354.80   # 15%
    elif base_ir_final <= 4664.68:
        ir = base_ir_final * 0.225 - 636.13  # 22.5%
    else:
        ir = base_ir_final * 0.275 - 869.36  # 27.5%
    
    # Garante que IR não seja negativo
    ir = max(ir, 0)
    
    # Cálculo final
    salario_liquido = salario_bruto - inss - ir
    
    return {
        'salario_bruto': salario_bruto,
        'inss': inss,
        'ir': ir,
        'dependentes': dependentes,
        'deducao_dependentes': deducao_dependentes,
        'salario_liquido': salario_liquido
    }

# Exemplo de uso
resultado = calcular_salario_liquido(5000.00, 2)
print(f"Salário líquido: R$ {resultado['salario_liquido']:.2f}")

# Configurações do sistema com valores padrão
config_sistema = {
    'debug': True,          # Modo debug ativo em desenvolvimento
    'timeout': 30,          # Timeout em segundos para requisições
    'max_tentativas': 3,    # Número máximo de tentativas de conexão
    'email_admin': '[email protected]',  # Email para notificações críticas
    'cache_enabled': False  # Cache desabilitado em desenvolvimento
}

class ContaBancaria:
    """
    Representa uma conta bancária simples.
    
    Attributes:
        numero (str): Número da conta
        titular (str): Nome do titular
        saldo (float): Saldo atual da conta
        ativa (bool): Status da conta
    """
    
    def __init__(self, numero, titular, saldo_inicial=0):
        """
        Inicializa uma nova conta bancária.
        
        Args:
            numero (str): Número da conta
            titular (str): Nome do titular
            saldo_inicial (float, optional): Saldo inicial. Default é 0.
        """
        self.numero = numero
        self.titular = titular
        self.saldo = saldo_inicial
        self.ativa = True  # Conta criada sempre ativa
        
    def depositar(self, valor):
        """Deposita um valor na conta."""
        if valor > 0 and self.ativa:
            self.saldo += valor
            return True
        return False
        
    def sacar(self, valor):
        """Saca um valor da conta se houver saldo suficiente."""
        if valor > 0 and valor <= self.saldo and self.ativa:
            self.saldo -= valor
            return True
        return False

def area_circulo(raio):
    """Calcula a área de um círculo."""
    import math
    return math.pi * raio ** 2

# Visualizando a documentação
help(area_circulo)
print(area_circulo.__doc__)

from typing import List, Dict, Union

def processar_vendas(vendas: List[Dict[str, Union[str, float]]]) -> float:
    """
    Processa uma lista de vendas e calcula o total.
    
    Args:
        vendas: Lista de dicionários com dados das vendas
               Cada dicionário deve conter 'produto' (str) e 'valor' (float)
               
    Returns:
        Total das vendas processadas
        
    Example:
        >>> vendas = [{'produto': 'Notebook', 'valor': 2500.00}]
        >>> processar_vendas(vendas)
        2500.0
    """
    total = 0.0  # Inicializa contador para soma
    
    for venda in vendas:  # Itera sobre cada venda
        # Adiciona valor da venda ao total (com validação)
        if 'valor' in venda and isinstance(venda['valor'], (int, float)):
            total += float(venda['valor'])
            
    return total

# ❌ Ruim - código obscuro que precisa de comentário
# Calcula a média ponderada dos últimos 30 dias
m = sum(v*p for v,p in zip(vals[-30:], pesos[-30:])) / sum(pesos[-30:])

# ✅ Melhor - código autodocumentado
def calcular_media_ponderada_30_dias(valores, pesos):
    """Calcula média ponderada dos últimos 30 dias."""
    valores_recentes = valores[-30:]
    pesos_recentes = pesos[-30:]
    
    soma_ponderada = sum(valor * peso for valor, peso in zip(valores_recentes, pesos_recentes))
    soma_pesos = sum(pesos_recentes)
    
    return soma_ponderada / soma_pesos

# ❌ Comentários desnecessários
x = 5  # Atribui 5 à variável x
y = x + 1  # Adiciona 1 ao valor de x e atribui a y
print(y)  # Imprime o valor de y

# ✅ Código limpo sem comentários óbvios
idade_minima = 18
idade_usuario = idade_minima + 1
print(f"Idade do usuário: {idade_usuario}")

def calcular_idade_aposentadoria(idade_atual, contribuicao_anos):
    """
    Calcula quando uma pessoa pode se aposentar.
    
    Args:
        idade_atual (int): Idade atual da pessoa
        contribuicao_anos (int): Anos de contribuição
        
    Returns:
        dict: Informações sobre aposentadoria
    """
    # Regras de aposentadoria (simplificadas)
    idade_minima = 65  # Idade mínima para aposentadoria
    contribuicao_minima = 35  # Anos mínimos de contribuição
    
    # Verifica se já pode se aposentar
    pode_aposentar = (idade_atual >= idade_minima and 
                     contribuicao_anos >= contribuicao_minima)
    
    if pode_aposentar:
        anos_restantes = 0
    else:
        # Calcula anos restantes para cada critério
        anos_idade = max(0, idade_minima - idade_atual)
        anos_contrib = max(0, contribuicao_minima - contribuicao_anos)
        anos_restantes = max(anos_idade, anos_contrib)
    
    return {
        'pode_aposentar': pode_aposentar,
        'anos_restantes': anos_restantes,
        'idade_aposentadoria': idade_atual + anos_restantes
    }

# Teste da função
resultado = calcular_idade_aposentadoria(55, 30)
print(f"Pode aposentar: {resultado['pode_aposentar']}")
print(f"Anos restantes: {resultado['anos_restantes']}")

def busca_binaria(lista_ordenada, item_procurado):
    """
    Implementa busca binária em lista ordenada.
    
    Args:
        lista_ordenada (list): Lista ordenada para busca
        item_procurado: Item a ser encontrado
        
    Returns:
        int: Índice do item ou -1 se não encontrado
    """
    # Inicializa ponteiros para início e fim da lista
    inicio = 0
    fim = len(lista_ordenada) - 1
    
    # Continua dividindo até encontrar ou esgotar opções
    while inicio <= fim:
        # Calcula posição do meio (evita overflow)
        meio = inicio + (fim - inicio) // 2
        
        # Verifica se encontrou o item
        if lista_ordenada[meio] == item_procurado:
            return meio  # Retorna índice encontrado
            
        # Se item procurado é menor, busca na metade esquerda
        elif lista_ordenada[meio] > item_procurado:
            fim = meio - 1
            
        # Se item procurado é maior, busca na metade direita
        else:
            inicio = meio + 1
    
    # Item não foi encontrado
    return -1

# Teste do algoritmo
numeros = [1, 3, 5, 7, 9, 11, 13, 15, 17, 19]
posicao = busca_binaria(numeros, 7)
print(f"Número 7 encontrado na posição: {posicao}")