Como documentar uma função de validação de CPF?

Documentar uma função de validação de CPF é essencial para garantir a manutenibilidade e o entendimento do código por outros desenvolvedores. Um bom exemplo de documentação segue um padrão claro, explicando o propósito, os parâmetros, o retorno e o funcionamento interno do algoritmo de validação.

Pré-requisitos

• Conhecimento básico em Python
• Editor de texto ou IDE para escrever o código

Passo 1: Definir a estrutura da função

Comece definindo a assinatura da função com uma docstring clara. A docstring deve explicar o propósito da função, os parâmetros de entrada, o tipo de retorno e possíveis exceções.

def validar_cpf(cpf: str) -> bool:
    """
    Valida um número de CPF (Cadastro de Pessoas Físicas).

    Args:
        cpf (str): String contendo o CPF a ser validado.
                   Pode conter pontos, traços ou espaços, que serão removidos.

    Returns:
        bool: True se o CPF for válido, False caso contrário.

    Raises:
        ValueError: Se o CPF não tiver 11 dígitos após a limpeza.
    """

Passo 2: Limpar e padronizar o CPF

Antes de aplicar o algoritmo de validação, é necessário remover caracteres não numéricos e garantir que o CPF tenha 11 dígitos.

    # Remover caracteres não numéricos
    cpf_limpo = ''.join(filter(str.isdigit, cpf))

    # Verificar se o CPF tem 11 dígitos
    if len(cpf_limpo) != 11:
        raise ValueError("CPF deve conter exatamente 11 dígitos.")

Passo 3: Implementar o algoritmo de validação

O algoritmo de validação de CPF consiste em calcular dois dígitos verificadores com base nos nove primeiros dígitos. Documente cada etapa do cálculo.

    # Verificar se todos os dígitos são iguais (CPFs inválidos)
    if cpf_limpo == cpf_limpo[0] * 11:
        return False

    # Calcular o primeiro dígito verificador
    soma = sum(int(digito) * (10 - i) for i, digito in enumerate(cpf_limpo[:9]))
    resto = soma % 11
    digito1 = 0 if resto < 2 else 11 - resto

    # Calcular o segundo dígito verificador
    soma = sum(int(digito) * (11 - i) for i, digito in enumerate(cpf_limpo[:10]))
    resto = soma % 11
    digito2 = 0 if resto < 2 else 11 - resto

    # Comparar os dígitos calculados com os informados
    return int(cpf_limpo[9]) == digito1 and int(cpf_limpo[10]) == digito2

Exemplo Prático

Conclusão

Com este método, você documenta uma função de validação de CPF de forma clara e profissional, facilitando a manutenção e o entendimento do código por outros desenvolvedores. A combinação de uma docstring bem estruturada e um algoritmo comentado garante que a função seja robusta e fácil de ser integrada em qualquer sistema.