Uma breve introdução ao estilo de codificação do Python

Apr 03 2023

Foto de Artturi Jalli no Unsplash

Quando decidi, alguns dias atrás, começar a escrever sobre Python, não tinha certeza de qual seria meu primeiro tópico. Principalmente porque nunca escrevi nenhum artigo na minha vida antes, e é bastante intimidador. Então pensei: “Tudo bem, vou começar com algo curto e simples para molhar os pés.”, então aqui estamos nós.

Daremos uma olhada rápida em algumas das diretrizes de estilo de codificação para Python, que nos ajudarão a escrever um código claro, consistente e fácil de ver.

Vamos mergulhar de cabeça!

Índice

Introdução
Convenções de nomenclatura
Para espaço em branco ou não para espaço em branco?
Diretrizes Gerais
Não Faça Tudo Sozinho

É provável que você já tenha ouvido falar sobre PEP , mas caso ainda não tenha ouvido, aqui está a definição formal:

PEP significa Python Enhancement Proposal. Um PEP é um documento de design que fornece informações para a comunidade Python ou descreve um novo recurso para Python ou seus processos ou ambiente

Há uma grande lista de PEPs abordando diferentes tópicos relacionados ao Python, mas vamos nos concentrar apenas no PEP 8 , que é a diretriz quando se trata de convenções de estilo de codificação do Python. Ele visa tornar o código mais legível e consistente, definindo um conjunto de diretrizes para convenções de nomenclatura, uso de tabulações versus espaços, comprimento máximo de linha, etc. No entanto, lembre-se de
que essas não são regras, às vezes faz sentido não seguir uma diretriz particular, veja alguns exemplos aqui: Uma Consistência Tola é o Duende das Mentes Pequenas

Convenções de nomenclatura

Vamos começar olhando para um exemplo simples. O que você acha dessas duas funções?

def sumEvenNumbers(numbers):
    even_sum = 0
    
    for ListNumber in numbers:
        if ListNumber % 2 == 0:
            even_sum += ListNumber

    return even_sum

def sum_odd_nums(nums):
    OddSum = 0
    
    for n in nums:
        if n% 2 == 0:
            OddSum+= n

    return OddSum

Agora você pode pensar: “Bem, Ahmed, e daí? Isso é realmente um grande problema? Eu diria que sim, por alguns motivos:

Muitas vezes, lemos o código mais do que o escrevemos, por isso é importante mantê-lo limpo e facilmente compreensível
É uma coisa a menos para se preocupar ao criar uma nova variável/função/classe, porque você já sabe como deve ser e só precisa criar um nome descritivo (não sei quanto a você, mas às vezes isso me leva um pouco)
Torna mais fácil escrever análises estáticas ou scripts de automação quando os padrões de nomenclatura são os mesmos em todos os lugares

Entre no PEP 8!

Ele fornece uma diretriz para os padrões de nomenclatura recomendados para variáveis, classes, funções e outros. Aqui estão alguns deles:

Aulas: use o estilo CamelCase (por exemplo class InputManager)
Funções e variáveis: use o estilo snake_case (ex. def sum_even_numbers(numbers)ou sum_even = 0)
Métodos: o mesmo que funções e, caso seja um método não público, use um sublinhado inicial (por exemplo, def _calculate_intermediate_sum(self))
Constantes: use todas as letras maiúsculas com sublinhados para separar as palavras (por exemplo, MAX_WIDTH = 10)

Nossa próxima ordem de negócios é o uso de espaços em branco. Este é puramente estético.

Para espaço em branco:

Um único espaço em cada lado dos operadores binários ( =, +=, -=, >, >=, <, <=, ==, etc.) (por exemplo sum += 5)
Um único espaço após a(s) vírgula(s) em tuplas/listas (por exemplo ages = [12, 13, 14], coordinates = (4, 3))
Em funções, digite dicas: um único espaço após os dois pontos e coloque um ->espaço em ambos os lados (por exemplo def sum_even(nums: List) -> int:, )
Quando um valor padrão é usado em combinação com uma dica de tipo em uma assinatura de função, use espaços em branco ao redor do =(por exemplo def draw(scale: int = 1) -> None:)
(eu não sabia disso antes de pesquisar para este artigo)

Não adicione espaços extras para alinhar os operadores
Antes da(s) vírgula(s) em tuplas/listas
Imediatamente dentro de parênteses, colchetes ou colchetes
Evite espaços em branco à direita

# Good
age = 20
social_security_number = 1111

info[0] = (names[0], {'address': 'somewhere'})

heights = [180, 178, 195]

# Bad
age                    = 20
social_security_number = 1111

info[ 0] = ( names[ 0 ], { 'address': 'somewhere' } )

heights = [180 , 178 , 195]

Há muitas outras diretrizes sobre as quais gostaria de falar, mas, para resumir, deixarei apenas algumas dicas rápidas (a descrição mais detalhada pode ser encontrada na documentação do PEP 8 ) :

As importações devem ser feitas em linhas separadas
Use espaço em vez de tabulações (exceto quando as tabulações já estiverem sendo usadas em sua base de código, pois o Python não permite misturar espaços e tabulações)
O comprimento máximo recomendado da linha é de 79 caracteres para código e 72 caracteres para comentários ou docstrings
Use 4 espaços por nível de recuo

Todos nós precisamos de ajuda de vez em quando e, quando se trata de seguir os padrões que discutimos, sua biblioteca preferida é autopep8. Esta ferramenta formata automaticamente seu código Python para estar em conformidade com o guia de estilo PEP 8, você também pode especificar o nível de agressividade e se deve ignorar algumas regras ao formatar ( Regras corrigidas por autopep8 )

Para instalá-lo:

pip install autopep8

E usá-lo é tão simples:

autopep8 --in-place --aggressive <filename>

Se você estiver desenvolvendo no Visual Studio Code, recomendo usar o recurso de formatação automática na extensão Python, onde ele é executado autopep8em um arquivo quando você o salva.

Uma breve introdução ao estilo de codificação do Python

Índice

Convenções de nomenclatura

Referências