Regras Fundamentais para Escrever Código Python

Por Ricardo Costa Val do Rosário

1. Convenções de Nomenclatura

- Mantenha nomes descritivos e consistentes para funções, variáveis e classes. 
 Isso facilita a leitura e a manutenção do código.

- Variáveis e funções: snake_case (ex.: media_aluno, calcula_media)
1. Classes: PascalCase (ex.: Aluno, Calculadora)
2. Constantes: UPPER_SNAKE_CASE (ex.: PI, TAXA_JUROS)

2. Estrutura e Indentação

1. Python usa indentação para definir blocos de código. 
2. Use sempre 4 espaços por nível de indentação.
3. Nunca misture espaços e tabs.
4. Configure seu editor para converter tabs em espaços.
5. Alinhe operadores em expressões longas apenas quando aumentar a clareza

3. Comentários e Docstrings

1. Explique o “porquê” do código, não o “como”. 
2. Use comentários para trechos complexos e docstrings para módulos, classes e funções.
3. • Comentários de linha: precedidos por #
4. • Docstrings de função/classe: strings triplas logo após a definição.
5. • Mantenha o texto conciso e atualizado.

def calcula_media(valores):
   Recebe uma lista numérica e retorna a média aritmética.
   
    return sum(valores) / len(valores)

4. Formatação de Código

1. • Siga o PEP 8 para manter um estilo uniforme em todo o projeto.
2. • Limite de 79 caracteres por linha.
3. • Linhas em branco: 2 antes de definições de classe/module, 1 antes de funções internas.
4. • Espaços em operadores e após vírgulas.

5. Importações

Coloque espaços ao redor de operadores binários e após vírgulas, mas sem exageros:

# Correto

x = a + b
func(arg1, arg2)

# Evite

x=a+b
func( arg1,arg2 )

• Organize as importações na ordem: padrão de terceiros e locais. 

• Separe cada grupo com uma linha em branco.

# Importações padrão

import os
import sys
[]()

# Bibliotecas de terceiros

import numpy as np
import pandas as pd


# Módulos locais

from meu_pacote.utils import ler_dados

6. Tratamento de Erros e Exceções

1. • Use exceções específicas.
2. • Evite blocos genéricos que mascaram erros indesejados.
3. • Prefira except ValueError: a except:
4. • Limite o bloco try ao menor escopo possível
5. • Use finally quando necessário para liberar recursos

Tipo	Convenção	Exemplo

Variáveis/Funções	snake_case	media_aluno, calcula_soma()

Classes	PascalCase	Aluno, ProcessadorDeDados

Constantes	UPPER_SNAKE	MAX_LINHAS, TAXA_JUROS

Módulos/Pacotes	short_snake	utils.py, meu_pacote

7. Tipagem e Anotação de Tipos

Agrupe e ordene em três blocos, cada um separado por linha em branco:

1. Bibliotecas da biblioteca padrão
2. 	Bibliotecas de terceiros
3. 	Módulos locais do projeto

Padrão

import os.
import sy

Terceiros

import numpy as np
import pandas as py

Locais

from meu_pacote.utils import ler_dados

• Anotações ajudam ferramentas:

De análise estática;
Leitores do código.

m typing import List, Dict

def processa_dados(dados: List[Dict[str, float]]) -> float:

• Anote apenas o necessário para clareza

• Use # type: ignore com moderação para casos excepcionais

8. Boas Práticas de Declaração de Variáveis

1. • Escolha o tipo de dado adequado e evite retribuições confusas.
2. • Atribuição múltipla apenas quando relacionada (ex.: x, y = 0, 1)
3. • Evite variáveis temporárias desnecessárias
4. • Prefira compreensões de lista/dicionário para criar coleções

9. Uso de Bibliotecas e Dependências

1. •  Gerencie pacotes com pip e registre dependências em requirements.txt ou pyproject.toml.
2. • Congelar versões mínimas necessárias
3. • Isolar ambientes com venv ou conda
4. • Documentar comandos de instalação

10. Ferramentas de Verificação e Automatização

Adote linters, formatadores e testes automatizados para garantir qualidade.

1. • Black ou YAPF para formatação
2. • Flake8 ou pylint para linting
3. • pytest para testes unitários
4. • Git hooks (pre-commit) para validações pré-commit

Ao aplicar essas regras, seu código Python ficará:

1. Mais legível, 
2. Em maior segurança
3. Adequadamente armazenado.

Onde Encontrar Documentação oficial em:

https://peps.python.org/pep-0008
 
 ``