Estilo de Código PEP 8 em Python

Introdução

Neste laboratório, você aprenderá a aplicar o guia de estilo PEP 8 ao seu código Python. O PEP 8 é o guia de estilo oficial para Python, fornecendo um conjunto de recomendações para escrever código legível e consistente. Seguir estas diretrizes torna seu código mais fácil de ser lido por você e por outros.

Você praticará a implementação de regras chave do PEP 8 para indentação, comprimento da linha, espaçamento e convenções de nomenclatura. Você também aprenderá a usar a ferramenta autopep8 para formatar seu código automaticamente, economizando tempo e garantindo a conformidade com os padrões da comunidade.

Compreender a Indentação e o Comprimento da Linha do PEP 8

A indentação adequada e o comprimento da linha são fundamentais para um código Python legível. Nesta etapa, você aprenderá e aplicará as diretrizes do PEP 8 para esses dois aspectos.

Indentação: O PEP 8 recomenda o uso de 4 espaços por nível de indentação. Esta é uma convenção forte na comunidade Python.

Comprimento da Linha: O PEP 8 sugere limitar todas as linhas a um máximo de 79 caracteres. Para docstrings e comentários, o limite é de 72 caracteres. Isso melhora a legibilidade, especialmente em telas menores ou ao comparar código lado a lado.

Vamos colocar isso em prática. No explorador de arquivos à esquerda, localize e abra o arquivo indentation_example.py. O código contido nele demonstra a indentação correta para definições de função e instruções de múltiplas linhas.

## Correct indentation using 4 spaces.
def long_function_name(
        var_one, var_two, var_three,
        var_four):
    print(var_one)

## Define some variables for demonstration.
var_one = "first"
var_two = "second"
var_three = "third"
var_four = "fourth"

## Aligning with the opening delimiter.
foo = long_function_name(var_one, var_two,
                         var_three, var_four)

## Using a hanging indent. The first line has no arguments,
## and subsequent lines are indented to distinguish them.
bar = long_function_name(
    var_one, var_two,
    var_three, var_four)

## A multi-line list.
my_list = [
    1, 2, 3,
    4, 5, 6,
]

## Calling the functions to produce output.
long_function_name("first call", "second", "third", "fourth")
foo = long_function_name("second call", "second", "third", "fourth")
bar = long_function_name("third call", "second", "third", "fourth")

Após revisar o código, execute o script para ver sua saída. Abra o terminal na parte inferior do WebIDE e execute o seguinte comando:

python ~/project/indentation_example.py

O script será executado e imprimirá o primeiro argumento de cada chamada de função. A saída será:

first call
second call
third call

Este exercício demonstra como a indentação consistente torna as chamadas de função complexas e as estruturas de dados muito mais fáceis de ler.

Praticar Espaçamento e Convenções de Nomenclatura

Espaçamento consistente e convenções de nomenclatura claras também são cruciais para a legibilidade do código. Esta etapa aborda as regras do PEP 8 para ambos.

Espaçamento:

Use um único espaço ao redor da maioria dos operadores (=, +=, ==, <, >).
Use um espaço após vírgulas em listas, tuplas e argumentos de função.
Evite espaços extras imediatamente dentro de parênteses, colchetes ou chaves.

Convenções de Nomenclatura:

snake_case: Use para funções e variáveis (ex: minha_funcao, nome_usuario).
PascalCase: Use para nomes de classes (ex: MinhaClasse).
UPPERCASE_SNAKE_CASE: Use para constantes (ex: MAX_CONEXOES).

Vamos ver essas regras em ação. No explorador de arquivos, abra o arquivo style_guide_example.py. O código inclui exemplos de espaçamento e nomenclatura corretos, com as versões incorretas comentadas para comparação.

## A constant
MAX_OVERFLOW = 100

## A class name in PascalCase
class MySampleClass:
    def __init__(self, name):
        ## A variable name in snake_case
        self.instance_name = name

    ## A function name in snake_case
    def sample_method(self, var_one, var_two):
        ## Correct spacing around operators and after comma
        result = var_one + var_two
        print(self.instance_name, result)

## --- Incorrect examples for comparison ---
## class mySampleClass:
##     def SampleMethod(self, varOne, varTwo):
##         result=varOne+varTwo
##         print(self.instance_name,result)

## Create an object and call the method
my_object = MySampleClass("TestObject")
my_object.sample_method(10, 5)

Salve o arquivo se você fez alguma alteração e execute-o a partir do terminal:

python ~/project/style_guide_example.py

A saída mostrará o nome do objeto e o resultado do cálculo:

TestObject 15

Ao seguir estas regras de espaçamento e nomenclatura, você torna a estrutura e o propósito do seu código imediatamente mais claros para qualquer leitor.

Usar `autopep8` para Formatação Automática

Formatar o código manualmente pode ser tedioso. Felizmente, existem ferramentas para automatizar esse processo. Nesta etapa, você instalará e usará o autopep8, uma ferramenta popular que reformata automaticamente o código Python para estar em conformidade com o guia de estilo PEP 8.

Primeiro, você precisa instalar o pacote autopep8. Abra o terminal e execute o seguinte comando. O sudo é usado para instalá-lo em todo o sistema.

sudo pip3 install autopep8

O processo de instalação começará, e você deverá ver uma saída confirmando sua instalação bem-sucedida:

Collecting autopep8
...
Successfully installed autopep8-X.Y.Z

Em seguida, vamos trabalhar com um arquivo Python que possui formatação deliberadamente ruim. No explorador de arquivos, abra unformatted_code.py e examine seu conteúdo:

a=1
b=2;
def  my_function ( arg1 , arg2 = 0 ):
    result = arg1+arg2
    print( result)

Este código apresenta vários problemas de estilo: espaçamento inconsistente, um ponto e vírgula redundante e espaços extras na definição da função.

Agora, vamos usar o autopep8 para corrigi-lo. O flag --in-place instrui a ferramenta a modificar o arquivo diretamente. Execute este comando no seu terminal:

autopep8 --in-place ~/project/unformatted_code.py

Após a conclusão do comando, abra unformatted_code.py novamente no editor. Você verá que o código foi limpo automaticamente:

a = 1
b = 2


def my_function(arg1, arg2=0):
    result = arg1 + arg2
    print(result)

Note como o autopep8 corrigiu o espaçamento, removeu o ponto e vírgula e adicionou duas linhas em branco antes da definição da função, conforme recomendado pelo PEP 8. Usar um formatador automático como o autopep8 é uma maneira altamente eficiente de manter um estilo de código consistente em seus projetos.

Juntando Tudo: Refatoração de um Script

Chegou a hora de aplicar tudo o que você aprendeu. Nesta etapa, você refatorará manualmente um script que viola várias diretrizes do PEP 8. Este exercício testará sua compreensão sobre indentação, espaçamento e convenções de nomenclatura.

Primeiro, abra refactor_challenge.py no explorador de arquivos. Ele contém o seguinte código, que calcula a área de um retângulo, mas está escrito com um estilo ruim.

## This script calculates the area of a rectangle and prints it.
def CalculateArea(width,height):
    Area = width*height ## calculate area
    return Area

w = 10
h = 5
rectangle_area=CalculateArea(w,h)
print("The area of the rectangle is:",rectangle_area)

Sua tarefa é editar manualmente este código no editor para torná-lo compatível com o PEP 8. Procure por problemas em:

Nomenclatura de Funções: Os nomes das funções devem ser em snake_case.
Nomenclatura de Variáveis: Os nomes das variáveis também devem ser em snake_case.
Espaçamento: Verifique o espaçamento adequado ao redor de operadores e após vírgulas.
Comentários: Comentários em linha devem ter um espaço após o #.

Reserve um momento para refatorar o código por conta própria. Depois de terminar, seu código deve se parecer com isto:

## This script calculates the area of a rectangle and prints it.
def calculate_area(width, height):
    """Calculate and return the area of a rectangle."""
    area = width * height  ## calculate area
    return area


w = 10
h = 5
rectangle_area = calculate_area(w, h)
print("The area of the rectangle is:", rectangle_area)

Note as mudanças: CalculateArea virou calculate_area, Area virou area, e o espaçamento foi corrigido. Também adicionamos uma docstring à função, que é uma boa prática para explicar o que uma função faz.

Salve suas alterações e execute o script para garantir que ele ainda funcione corretamente:

python ~/project/refactor_challenge.py

A saída deve ser:

The area of the rectangle is: 50

Este exercício demonstra que refatorar para o estilo não altera o que o código faz, mas melhora drasticamente sua legibilidade e manutenibilidade.

Resumo

Neste laboratório, você aprendeu os fundamentos do guia de estilo PEP 8 para Python. Você praticou a aplicação de regras para indentação, comprimento de linha, espaçamento e convenções de nomenclatura. Você também descobriu o poder do autopep8 para formatar automaticamente seu código de modo a atender a esses padrões. Ao completar um desafio final de refatoração, você juntou todos esses conceitos para transformar um script mal estilizado em código Python limpo, legível e de fácil manutenção. Aderir ao PEP 8 é uma prática fundamental para qualquer desenvolvedor Python profissional, pois promove a colaboração e melhora a qualidade do código.