Baixe Boas práticas coom Python e outras Esquemas em PDF para Programação em Python, somente na Docsity!
Boas Práticas com Python
Felipe C. R. dos Santos, ByLearn
1 Boas Práticas com Python
Apenas criar um código e fazê-lo funcionar não é o bastante, ainda mais se você pretende trabalhar em uma grande empresa, onde o trabalho em equipe é essencial. Seu código, para poder ser melhor entendido e mais facil de dar manutenção/atualização pelos seus colegas (e até mesmo por você), precisa ser bem escrito , isto é, ser bem estruturado, organi- zado e padronizado. Para isso, você sempre deve seguir as Guidelines e Best Practices da linguagem que está trabalhando. Neste curso iremos nos atentar justamente a isso:
- Como escrever um código em Python da maneira certa
2 Entendendo Estruturas de Projetos
Quando ouvimos falar de estruturar um código pela primeira vez pode parecer algo difícil e complicado, ou que essa estrutura seja algo bem matemático e complexo, não é mesmo? Porém, quando dizemos em estruturar o código estamos falando apenas sobre decisões a se tomar para, aproveitando todos os re- cursos da linguagem, criar um código limpo e eficaz. Basicamente, um código bem estruturado é aquele código limpo, fácil de entender, com a lógica clara e evidente em todas as etapas. Além disso, também espera-se ele ser bem organizado , tendo seus arquivos e pastas bem divididos e setorizados. Dessa forma, com o código bem estruturado e organizado, fica fácil qualquer um (tanto nós como nossos colegas de trabalho) en- tendermos bem o que cada parte do código faz, porquê ela faz aquilo e como ela faz.
Pronto! Dessa maneira o código deixa de ser um monstro de sete cabeças que nem o criador consegue domar e se torna bem mais fácil darmos manutenção no código e criarmos funcionali- dades novas, não concorda? Falando assim pode até continuar parecendo difícil e compli- cado, mas te garanto que é bem fácil, ainda mais tendo o apoio de toda uma comunidade de desenvolvedores que já passaram por isso antes e decidiram compartilhar seus próprios métodos para resolver estes problemas. Sendo assim, prepare já o seu café, pois já vamos começar com o aprendizado das Boas Práticas com o Python!
2.1 Organizando seu projeto
Para organizarmos nosso projeto, a maneira mais fácil e recomen- dada para isso consiste em dar nomes claros e específicos para cada arquivo. Nunca nomeie um arquivo de x.py ou mat_mul.py, prefira algo mais fácil de entender ao ler, como multiplicar.py. Além disso, evite deixar seus arquivos de códigos espalhados por aí, cria pastas e coloque-os lá dentro. Caso você tenha os arquivos multiplicar.py, dividir.py, subtrair.py e adicionar.py, porque não criamos a pasta matematica e colocar- mos todos esses arquivos lá dentro? Até mesmo coisas básicas como esta ajudam muito na hora de organizarmos e entendermos nosso código.
2.1.1 Organizando Módulos
Na hora de organizar seus módulos, busque sempre nomes cur- tos, evite precisar fazer uso de underlines e separadores e jamais misture nome com namespace (“pasta onde está o arquivo”). Exemplo:
- Ao invés de usar os nomes bylearn_curso e bylearn_ebook, eu pode- ria criar a pasta bylearn e dentro dela colocar os arquivos curso e **ebook.
- Dessa forma usaremos apenas bylearn.curso e bylearn.ebook.
- Assim, bylearn torna-se o namespace*. Além de ficar melhor visivelmente, também faremos mais jus ao uso das pastas para segmentar e organizar nossos arquivos.
exemplo o versionamento de código (controle das versões do pro- jeto). O principal e mais famoso site para isso é o Github. Portanto, nada mais justo do que aprendermos a estrutura básica de um repositório e como melhorarmos nossa arquitetura.
3.1 A Estrutura Básica
Como nosso curso é focado em Python, por mais que a boa prática da organização de repositórios seja algo geral para todas as lin- guagens, vamos ser mais específicos ao Python no momento, abordando os arquivos e arquitetura padronizados para essa tão amada linguagem.
3.1.1 Organização e Ordenação
Os repositórios são comumente organizados na seguinte ordem:
- Título do Projeto
- Descrição do Projeto
- Arquivos do Projeto
- Conteúdo do Readme (Leia-me)
Dessa forma, podemos entender que se um projeto não possui um título claro e uma boa descrição, é mais difícil o usuário de- scer a tela até ver seus arquivos. Porém, ainda é bem provável ele chegar até seus arquivos, mas aqui que mora o problema... Imagina você se deparando com um projeto de 2000 arquivos, todos na mesma pasta e com nomes aleatórios. Eu desistiria do projeto, você faria o mesmo, não? Pois é, por isso é importante organizarmos bem nossos ar- quivos, dando uma boa estrutura para eles, para que tire o medo do programador que visitar seu repositório e faça com que ele con- tinue descendo a tela, lendo melhor o seu Readme e entendendo seu projeto.
3.1.2 Arquivos
README.md
- O Readme é o arquivo principal para descrever e explicar nosso projeto, através do Markdown (por isso a extensão md), podemos
escrever de uma forma bem organizada as informações principais do nosso projeto. LICENSE.md
- É o arquivo que contém informações sobre a licença de uso e distribuição do nosso repositório. Por ser código aberto, é acon- selhavel buscar licenças mais ‘liberais’, que não limite o seu uso por parte de quem usar nosso código. setup.py - É o arquivo de instalação do nosso projeto, basta o programador baixar nosso repositório e rodar esse arquivo. requirements.txt
- Como falamos anteriormente, não podemos ficar recriando a roda, então provavelmente nosso código também possui códigos, módulos e bibliotecas externas. Neste arquivo detalhamos quais os requisitos externos para utilizar nosso código. Makefile
- O Make no Python pode não ser tão usual quanto na linguagem C, mas o Makefile é um arquivo muito útil para definirmos tarefas genéricas ao nosso projeto. Não é um arquivo obrigatório, mas bem recomendado caso seja viável ao seu projeto.
3.1.3 Pastas
“root” - Root é como chamamos nossa pasta raíz, isto é, aquela ini- cial do nosso projeto. É nela onde vamos inserir todos os arquivos ditos acima e todas as pastas abaixo. docs
- Esta é a pasta responsável pela documentação do nosso pro- jeto, caso você tenha um projeto grande, ficará inviável dar manutenção e aprimorá-lo sem ter uma documentação, e é jus- tamente nessa pasta que você irá colocá-la. tests
- Não é porque um código está rodando que ele está funcionando. Nós precisamos testá-lo para garantir que todas as partes estão ex- ecutando corretamente. Caso você tenha alguma rotina de testes automatizados, é aqui que você irá inserir os arquivos. nome_do_pacote - Agora precisamos apenas criar uma pasta com nome do nosso pacote ou projeto e colocar seus arquivos aqui dentro. Lembrando que os arquivos do projeto também de- vem estar organizados, separados por pastas e com nomes bem definidos, como comentamos anteriormente. Um bom exemplo de repositório neste modelo pode ser visto em: https://github.com/navdeep-G/samplemod
Esse Guideline foi escrito em 2001 por Guido van Rossum, Barry Warsaw e Nick Coghlan, sendo que Guido é o criador do Python.
6.1 Nomeclatura
A principal informação que temos que ter antes de aprender até mesmo as regrinhas de nomeclatura é saber que:
Explícito é melhor do que implícito. Sendo assim, não importa o que for nomear, sempre deixe de uma maneira intuitiva e que expresse a real motivação para a sua criação. Como por exemplo:
- Não nomeie uma variável de var1 , coloque algo mais intu- itivo, como resultado_multiplicacao.
- Não chame de velo_leop (implícito) quando pode chemar de velocidade_leopardo (explícito).
- Não cause ambuiguidade. desligar() é diferente de desli- gar_pc() e desligar_servidor(). Além disso, vale lembrar que o simples é melhor que o com- plexo. Sempre tente utilizar palavras pequenas e fáceis. Agora que já sabemos disso vamos aprender como nomear as coisas no Python!
6.1.1 Variáveis
- Use apenas letras minúsculas.
- Caso precise de mais de uma palvra, use underlines para melhor a visualização e leitura.
- Evite usar apenas uma letra no nome, com exceções aos ca- sos de variáveis temporárias de iteração. Exemplos:
- resultado_divisao.
- media_alunos_escola.
- nome.
- for i in items.
- Embora seja só uma letra, é uma variável temporária e para iter- ação, tendo sua função explicitamente a mostra.
6.1.2 Funções e métodos
- Use apenas letras minúsculas.
- Caso precise de mais de uma palvra, use underlines para melhor a visualização e leitura.
- Nunca use apenas uma letra.
Exemplos:
- calcular_media().
- renomear_aluno().
- somar().
6.1.3 Módulos
- Use apenas letras minúsculas.
- Evite usar mais de uma palavra, mas caso precise, separe-as por underline.
- Não use o namespace no nome do arquivo, mesmo que sep- arado por underline.
Exemplos:
- calculadora.py.
- helpers.py.
- rede_neural.py.
- Não use testes_cadastro e testes_formularios, use testes.cadastro e testes.formularios.
- No caso, testes é um namespace e não deve estar presente.
- Não use meu_formulario.py, use formulario.py.
- No caso, evitar nomes compostos desnecessários, deixe nomes curtos.
6.1.4 Pacotes
- Use apenas letras minusculas.
- Evite precisar de mais de uma palavra, mas caso seja necessário, não as separe.
Exemplos:
- calculadora.
- bpylearn.
- redeneural.
def funcao_top_level(): return None
6.2.2 Métodos dentro de classes
- Deixe apenas uma linha em branco entre os métodos dentro das classes.
- O primeiro método fica ‘colado’ na classe.
Exemplo:
class Classe: def primeiro_metodo(self): return None
def sgundo_metodo(self): return None
6.2.3 Funcionalidades dentro dos métodos
- Deixe uma linha em branco entre blocos de funcionalidades distintas.
- Em outras palavras, separe as partes da sua lógica para melhor visualização.
- A primeira linha do método sempre fica colado com sua definição.
Exemplo:
def calcular_media(): nome = 'Felipe' primeira_prova = 10 segunda_prova = 9
soma_notas = primeira_prova + segunda_prova quantidade_provas = 2
return soma / quantidade_provas
6.3 Tamanho máximo das linhas
Para melhor visualização do conteúdo de cada linha, gerando maior legibilidade ao código, o PEP8 usa um limite máximo de caracteres por linha, onde nenhuma linha deve conter mais do que 79 caracteres. Porém, nem sempre é possível uma linha/operação/rotina/função ter menos de 79 caracteres orig- inalmente e nesses casos, é preciso quebrar a linha, ‘separando’ seu conteúdo. Como adendo, é legal sabermos que o limite de 79 caracteres é para linhas de código, já para linhas de comentários o limite é de 72, mas veremos isso de forma mais detalhadas nos capitulos seguintes. Abaixo vemos algumas formas de se concatenar essas linhas e conseguir ficar dentro do limite imposto pelo PEP8:
6.3.1 Separando argumentos por vírgula
def minha_funcao(arg_um, arg_dois, arg_tres, arg_quatro): return arg_one
6.3.2 Separando por barra invertida
from meu_pacote import exemplo1,
exemplo2, exemplo
6.3.3 Operadores binários
total = (primeira_variavel
6.3.4 Strings longas
string = ("minha " "string em " "multiplas " "linhas")
x = 'Boas Práticas com Python' # Nome do curso
Correto:
nome_curso = 'Boas Práticas com Python'
6.4.3 Documentação (docstring)
Para as boas práticas na documentação o PEP8 informa apenas poucas coisas, sendo elas:
- Usar três aspas duplas no lugar de três aspas simples;
- Comentar apenas o necessário, mas de forma clara;
- Iniciar na mesma linha que usar as três aspas duplas;
- Finalizar os docstrings em linha extra (sem texto);
- Alinhar o texto com o início da primeira aspas;
- Documentar todos métodos, classes, módulos e funções públicas.
Já para o conteúdo e organização dentro do seu docstring, isso fica livre segundo a PEP8, porém, temos a PEP257 que é bem aceita. Em resumo, a PEP257 diz para separarmos por blocos os parâmetros, atributos, retornos e afins, deixando uma linha de “cabeçalho” seguida de uma linha de traços no início de cada um desse bloco separador. Por exemplo, seguinto tanto a PEP8 quanto a PEP257 temos:
def fazer_pipoca(sabor, tempo): """ Essa função faz pipoca no microondas.
Parametros
sabor : str Sabor da sua pipoca. tempo : int Tempo para fazer a pipoca.
Retorno
Retornará um objeto do tipo Pipoca com o sabor escolhido. """
pipoca = escolher_pipoca(sabor) modo = microondas.modo('pipoca',tempo)
return microondas(modo,sabor)
A principal função das docstrings são nos ajudar a entender melhor a classe/método/função/pacote, sabendo seu objetivo e funcionamento. Para isso basta usar a função help() e passar por parâmetro o que queremos ajuda.
help(fazer_pipoca)
Com isso temos de retorno o seguinte:
Help on function fazer_pipoca in module main:
fazer_pipoca(sabor, tempo) Essa função faz pipoca no microondas.
Parametros
sabor : str Sabor da sua pipoca. tempo : int Tempo para fazer a pipoca.
Retorno
Retornará um objeto do tipo Pipoca com o sabor escolhido.
Caso não seja preciso realizar muitos comentários na docu- mentação (se uma linha apenas bastar), você pode tanto abrir quanto fechar as aspas duplas na mesma linha, como no exemplo abaixo:
def mostrar_nome(): """ Mostrará o meu nome na tela """ print(meu_nome)
6.4.4 Não alimente o óbvio
Comentar e documentar é não só recomendável como im- pressindível para que seu código esteja de acordo com as boas
return arg_one
Incorreto:
def minha_funcao(arg_um, arg_dois, arg_tres, arg_quatro): return arg_one
Ou seja, os argumentos estão alinhados.
6.5.3 Abertura e fechamento de chaves e colchetes
Por fim, o PEP8 também ajuda na hora de identar a abertura e o fechamento de Chaves {} e Colchetes []. Como algumas vezes teremos que quebrar linhas que contem- plam listas, será necessário quebrar a abertura e fechamento dos colchetes. Uma recomendação do PEP8 é abrir a lista [ na linha em que definimos a variável, mas começar a inserir os dados nas linhas de baixo. Já para o fechamento, também inserí-lo em uma linha extra (após terminar de inserir os dados), alinhada com o primeiro elemento da lista, como no exemplo abaixo:
lista_numeros = [ 1, 2, 3, 4, 5, 6, 7, 8, 9 ]
6.6 Espaçamento entre caracteres
O PEP8 também irá te auxiliar sobre os espaçamentos entre carac- teres, segundo ele você deve usar caracteres nos seguintes casos:
- Operadores de Atribuição: - = , += , -=...
- Comparações: - == , != , > , <=...
- is , is not , in , not in.
- Booleanos: - and , not , or.
- Operadores matemáticos: - + , - , / , *****.
Sendo assim, temos como exemplo os seguintes usos:
if x == 0: x += y
if y not in z: print(y + x)
if cond1 and cond2: lista = []
Porém, veja como fica estranho essa regra ao tivermos mais de um dos casos listados acima acontecendo na mesma expressão, como duas comparações, dois booleanos, booleanos e operações e etc...
if y > 0 and x + 1 > z: if y not in z and x is not y: print("Versão estranha")
Para isso, o PEP8 criou uma solução onde apenas a operação de menor importância/prioridade deve ter espaçamento, as de- mais ficam sem espaço. Além disso, o uso do bom e velho parên- teses não mata ninguem, veja como tudo fica mais claro:
if y>0 and x+1>z: if (y not in z) and (x is not y): print("Versão melhorada")
Veja em outros exemplos: Errado:
y = x ** 2 + 5 z = (x + y) * (x - y)
6.8.1 Comparação de Booleano com True e False
Sabendo que um booleano já recebe um valor de verdadeiro e falso e toda comparação por trás dos panos valida apenas a veracidade da condição (se é verdadeira ou falsa), fica redundante checar se algo é ou não true. Sendo assim, devemos evitar o uso do == True ou == False. Errado:
meu_bool = 10 > 5 if meu_bool == True: print("10 é maior do que 5")
meu_segundo_bool = jogador.vencer if meu_segundo_bool == False: print("O jogador perdeu") Correto:
meu_bool = 10 > 5 if meu_bool: print("10 é maior do que 5")
meu_segundo_bool = jogador.vencer if not meu_segundo_bool: print("O jogador perdeu")
6.8.2 Sequências vazias
Sempre que for fazer alguma comparação com sequências vazias, elas devem ser falsas na validação do if. Embora pareça que uma lista vazia seja aquela cuja compara- ção do len() seja 0, o Python também já daria diretamente o valor de falso para ela, sendo assim, podemos evitar o uso do len da seguinte forma: Errado:
minha_lista = [] if not len(minha_lista): print('A lista está vazia!') Correto:
minha_lista = [] if not minha_lista: print('A lista está vazia!')
6.8.3 Usar is not é melhor do que not... is
Para gerar melhor legibilidade no seu código, dê preferência ao is not, ele é mais fácil de ler e entender do que o not... is, veja o exemplo abaixo: Errado:
if not x is None: return 'x existe!'
Correto:
if x is not None: return 'x existe!'
6.8.4 Saiba quando checar o None
Muitas vezes, checar se é True ou False não é bem o que esperamos, como por exemplo, para a seguinte função:
def calcular_idade(ano_nascimento,ano_atual=None): if not ano_atual: print("Você não informou o ano atual, calcule sua idade usand return
idade = ano_atual - ano_nascimento print("Você fez/fará", idade, "anos neste ano")
Parece que a função está correta, não é mesmo? Veja uns ex- emplos abaixo:
calcular_idade(1996,2019)
Output = Você fez/fará 23 anos neste ano
calcular_idade(1996)
Output = Você não informou o ano atual, calcule sua idade us- ando o ano atual e subtraindo 1996 Porém, o que acontece se nós voltarmos ao passado e entregar esse programa para algum morador do ano Zero? Ok... Provavel- mente ele iria assutar e sair correndo, mas quando ele entendesse a tecnologia e usasse o programa, veja o que aconteceria:
calcular_idade(-50,0)
