6 práticas recomendadas de Python para um código melhor

A codificação é a arte de escrever as instruções - também conhecidas como algoritmos - para que um computador realize uma tarefa específica. Para se comunicar com os computadores, os desenvolvedores usam linguagens de programação.

Assim como as linguagens naturais, como o inglês, o russo ou o quíchua, as linguagens de programação compreendem um conjunto específico de regras sintáticas e semânticas que fornecem os fundamentos da comunicação. Embora as linguagens naturais sejam mais complexas, flexíveis e dinâmicas, esses atributos também se aplicam, embora de forma mais limitada, às linguagens de programação. 

Você pode escrever até mesmo o algoritmo mais simples de várias maneiras diferentes. Embora seja desejável alguma flexibilidade no desenvolvimento de código, ela pode comprometer a eficiência e a comunicação eficaz, especialmente quando várias pessoas estão trabalhando nele.

Dessa forma, a legibilidade é um aspecto fundamental ao escrever o código. Para garantir que os desenvolvedores estejam na mesma página, a maioria das linguagens de programação desenvolveu padrões de codificação. Esses documentos fornecem diretrizes e práticas recomendadas para produzir código legível, sustentável e dimensionável. 

Neste artigo, descobriremos as práticas recomendadas de codificação para Python, uma das linguagens de ciência de dados mais populares. As práticas apresentadas nas seções a seguir baseiam-se principalmente no PEP 8, o guia padrão de práticas recomendadas para escrever código em Python. Para saber mais sobre o uso do Python, consulte nosso artigo ou nosso curso de Introdução ao Python. 

O que é o PEP 8?

"O código é lido com muito mais frequência do que é escrito. O código deve sempre ser escrito de uma forma que promova a legibilidade" - Guido van Rossum, o inventor do Python

O PEP 8 é um guia de estilo para o código Python. Escrito em 2001 por Guido van Rossum, Barry Warsaw e Nick Coghlan, o PEP 8 fornece um conjunto de recomendações para escrever códigos mais legíveis e consistentes. Ele abrange tudo, desde como nomear variáveis até o número máximo de caracteres que uma linha deve ter. 

PEP significa Python Enhancement Proposal (Proposta de aprimoramento do Python). Um PEP é um documento que descreve novos recursos propostos para o Python e documenta aspectos do Python, como design e estilo.

Embora não seja obrigatório, grande parte da comunidade Python usa o PEP 8. Portanto, é altamente recomendável seguir as diretrizes. Ao fazer isso, você melhorará suas credenciais como programador profissional. 

Apesar da ampla aceitação do PEP 8, as diretrizes podem não se adequar a todos os cenários específicos. Nesses casos, é uma prática comum as empresas definirem suas próprias convenções.

6 Práticas recomendadas de Python 

Práticas recomendadas de Python para qualidade de código

Escrever códigos legíveis e organizados pode fazer a diferença e aumentar suas perspectivas de carreira. Embora a codificação possa parecer um processo mecânico e complexo para iniciantes, a verdade é que a codificação é uma arte. 

Há muitas dicas que você pode seguir para aumentar a qualidade do código em Python. Aqui está uma lista de alguns dos mais relevantes.

A tirania da indentação

A indentação refere-se aos espaços no início de uma linha de código. Enquanto a indentação em outras linguagens de programação é apenas um recurso para facilitar a leitura, a indentação em Python é obrigatória. O Python usa a indentação para abrir um bloco de código. Mais precisamente, 4 espaços consecutivos por nível de recuo, conforme mostrado no código a seguir:

for number in [1,2,3,4]:
    if number % 2 == 0:
        print(number)
    else:
        continue

Comprimento máximo da linha

A PEP 8 recomenda que nenhuma linha tenha mais de 79 caracteres. Isso faz sentido, pois linhas mais curtas são mais fáceis de ler. Além disso, esse comprimento permite que você tenha vários arquivos abertos um ao lado do outro.

Linhas em branco

Cerque as definições de funções e classes de nível superior com duas linhas em branco. As definições de métodos dentro de uma classe são cercadas por uma única linha em branco. Linhas em branco extras podem ser usadas (com moderação) para separar grupos de funções relacionadas. Por fim, use linhas em branco nas funções (com moderação) para indicar seções lógicas. 

Use linters e autoformatadores

O domínio do código leva tempo. Prestar atenção a todos os detalhes durante a codificação pode ser um desafio e consumir muito tempo. Felizmente, as máquinas podem nos ajudar a garantir a qualidade do código, em especial os linters e formatadores. 

Os Linters realizam a análise estática dos códigos-fonte e verificam se há discrepâncias simânticas. Os formatadores são ferramentas semelhantes que tentam reestruturar o espaçamento do código, o comprimento da linha, o posicionamento dos argumentos e assim por diante para garantir que o código tenha uma aparência consistente em diferentes arquivos ou projetos. O Python oferece uma infinidade de linters e formatadores para você escolher.

Tenha em mente os princípios

Embora algumas das regras mencionadas acima sejam diretas, na maioria das vezes, a codificação é uma questão de bom gosto e intuição. Para se tornar um artista da codificação, você deve conhecer alguns dos princípios que sustentam o Python. Um ótimo exemplo desses princípios é o Zen of Python, abordado em um artigo separado.  

Práticas recomendadas de registro em Python

O registro em log é um meio de rastrear eventos que ocorrem quando algum software é executado. Especialmente quando os aplicativos aumentam em tamanho e complexidade, o registro torna-se uma técnica essencial para o desenvolvimento, a depuração, a execução e o acompanhamento do desempenho.  

Para lidar com as práticas de registro, o módulo de registro faz parte da Biblioteca Padrão do Python desde a versão 2.3. O módulo é o primeiro pacote a ser utilizado pela maioria dos desenvolvedores Python quando se trata de registro. Ele é amplamente descrito no PEP 282.

O registro em log é semelhante em espírito a uma função de impressão. No entanto, uma função de impressão carece de muitas informações que podem ser úteis para um desenvolvedor. O registro em log, no entanto, pode registrar os carimbos de data/hora e o número da linha em que o erro ocorreu. Ele também pode registrar erros ou qualquer informação em arquivos, soquetes, etc.

Para importar o módulo, você só precisa executar este código:

import logging

Nem todas as mensagens de registro são semelhantes. De fato, o módulo fornece uma categoria de níveis de registro de acordo com a gravidade da mensagem. É o seguinte:

• NOTSET (0): Isso significa que todas as mensagens serão registradas.
• Depurar (10): Útil para diagnosticar problemas no código. 
• Informações (20): Ele pode funcionar como um reconhecimento de que não há erros no código. Um bom caso de uso do registro em nível de informações é o progresso do treinamento de um modelo de aprendizado de máquina. 
• Advertência (30): Indicativo de um problema que pode ocorrer no futuro. Por exemplo, um aviso de um módulo que pode ser descontinuado no futuro ou um aviso de baixa rotação. 
• Erro (40): Um bug grave no código; pode ser um erro de sintaxe, um erro de falta de memória ou exceções. 
• Crítico (50): Um erro devido ao qual o programa pode parar de funcionar ou pode ser encerrado abruptamente.

import logging
logging.info('This message is just informative')
logging.debug('My missions is to provide information about debugging.')
logging.critical("A Critical Logging Message")

Dito isso, abaixo você encontrará uma lista de seis práticas recomendadas ao lidar com o registro em Python.  

Use logs em vez de impressões

Dissemos anteriormente que os registros fornecem informações da mesma forma que as funções de impressão. No entanto, os registros são muito mais avançados, pois podem fornecer informações mais granulares. 

A função Print pode ser tentadora, especialmente se você não estiver familiarizado com as rotinas de registro, mas os registros sempre serão a opção mais segura. Eles são mais adequados para dimensionar e lidar com aplicativos complexos. 

A Web está repleta de guias e documentação. Por exemplo, este tutorial de registro em log do DataCamp pode ser o que você está procurando para começar.

Use o módulo de registro 

Esse módulo é a opção ideal para a maioria dos desenvolvedores de Python. Isso significa que o módulo é bem mantido e apoiado por uma enorme comunidade que sempre terá uma resposta para suas dúvidas.

Escolha o nível de registro de forma inteligente

O módulo de registro é fornecido com seis níveis diferentes de mensagens. Cada um deles foi projetado para uma finalidade específica. Quanto mais você se ater a elas, mais fácil será para você e para os usuários entenderem o que está acontecendo no seu código.

Use carimbos de data e hora ao registrar

Esse é um recurso essencial dos registros que as funções de impressão não têm. Além de saber onde o problema apareceu, é importante saber quando ele ocorreu. Os registros de data e hora são seus maiores aliados nessas situações. Certifique-se de usar o formato padrão para gravar registros de data e hora, ou seja, o formato ISO-8601.

Esvaziar o compartimento de registro

Use classes RotatingFileHandler, como TimedRotatingFileHandler, em vez de FileHandler, para arquivar, compactar ou excluir arquivos de registro antigos para evitar problemas de espaço na memória. Essas classes limparão o espaço quando um limite de tamanho ou uma condição de tempo for acionada.

Práticas recomendadas de comentários em Python

Os comentários são muito importantes para fazer anotações para futuros leitores do nosso código. Embora seja difícil definir como o código deve ser comentado, há certas diretrizes que podemos seguir: 

• Qualquer comentário que contradiga o código é pior do que nenhum comentário. Por isso, é muito importante que atualizemos o código e não nos esqueçamos de atualizar os comentários para evitar a criação de inconsistências. 
• Os comentários devem ser frases completas, com a primeira letra em maiúscula. 
• Tente escrever comentários em inglês. Embora todos tenham a liberdade de escrever seus comentários no idioma que considerarem apropriado, recomenda-se que o façam em inglês. 
• Certifique-se de que seus comentários sejam claros e facilmente compreensíveis para outros falantes do idioma em que você está escrevendo.

Há dois tipos de comentários: comentários em bloco e comentários em linha. 

Um comentário de bloco explica o código que o segue. Normalmente, um comentário de bloco é recuado no mesmo nível do bloco de código. Cada linha de um comentário de bloco começa com um # e um espaço simples, como segue:

# This is a block comment
print('Welcome to DataCamp!")

Por outro lado, os comentários inline aparecem no mesmo nível do código. Os comentários em linha devem ser separados por pelo menos dois espaços da declaração. Semelhante a um comentário em bloco, um comentário inline começa com um único sinal de hash (#) e é seguido por um espaço e uma string de texto. 

print ("Have you ever tried Python?") # This is an inline comment

Práticas recomendadas de docstring do Python

Uma docstring é uma literal de string que ocorre como a primeira instrução em uma definição de módulo, função, classe ou método. Normalmente, você usa uma string de documentação para gerar automaticamente a documentação do código. Dessa forma, uma docstring pode ser acessada em tempo de execução usando o atributo especial obj.__doc__ desse objeto.

Para fins de consistência, as cadeias de documentos são sempre colocadas entre aspas duplas triplas (""").

Há duas formas de docstrings: as de uma linha e as de várias linhas. As frases de efeito são para casos realmente óbvios. Eles realmente deveriam caber em uma linha. O exemplo a seguir ilustra uma docstring de uma linha na função multiply():

def multiply(x, y):
    """ Return the product of two numbers """
    result = x * y
    return result

Por outro lado, uma docstring de várias linhas pode abranger várias linhas. Essa docstring deve documentar a função do script e a sintaxe da linha de comando, as variáveis de ambiente e os arquivos. As mensagens de uso podem ser bastante elaboradas e devem ser suficientes para que um novo usuário use o comando corretamente.

def calculate_salary(hours, price=20):
    """ Return the salary according to the hours worked

    Arguments:
    hours: total hours investe
    price: price of each hours worked. Minimum price is 20 dollars
    """
    salary = hours * price
    return salary

Uma explicação mais detalhada sobre docstrings pode ser encontrada na PEP257.

Práticas recomendadas de documentação do Python

Embora os comentários sejam importantes para que os outros desenvolvedores com quem você está trabalhando entendam o seu código, a documentação destina-se a ajudar uma comunidade de usuários em potencial a usar o seu software. Essa é uma etapa fundamental: não importa a qualidade do seu software, se a documentação não for boa o suficiente ou, pior ainda, não existir, as pessoas não o usarão. 

Especialmente se estiver trabalhando em um novo projeto, é sempre uma boa prática incluir um arquivo README. Esses arquivos normalmente são o principal ponto de entrada para os leitores do seu código. Elas incluem informações gerais para usuários e mantenedores do projeto. 

Embora conciso, o arquivo README deve explicar o objetivo do projeto, o URL da fonte principal do software e as informações de crédito.

Da mesma forma, você deve sempre incluir um arquivo setup.py, que garante que o software ou a biblioteca foi empacotado e distribuído com o Distulils, que é o padrão para a distribuição de módulos Python.

Além disso, se o seu software exigir outras dependências ou pacotes para ser executado, você deverá incluir um arquivo requirements.txt que descreva as dependências necessárias e suas versões.

Por fim, você pode adicionar qualquer outra informação que considere relevante para os usuários em potencial. Por exemplo, uma boa prática é fornecer exemplos de como seu pacote ou funções funcionam. 

Práticas recomendadas do ambiente virtual Python 

Para garantir a ordem e a consistência em seus projetos de dados, uma boa prática é criar um ambiente virtual para cada projeto que você iniciar. 

O ambiente virtual, também conhecido como virtualenvs, ajuda a desacoplar e isolar as versões do Python e as bibliotecas necessárias para o seu projeto, bem como as respectivas versões do pip. Isso autoriza os usuários finais a instalar e gerenciar seu próprio conjunto de software e versões, independentemente daqueles fornecidos pelo sistema. 

Para criar o virtualenvs, precisamos instalar primeiro o pacote necessário, escrevendo a seguinte linha de código em seu terminal:

pip install virtualenv

Para criar um novo virtualenv, o código a seguir fará a mágica. Estamos chamando o novo virtualenv de "new_venv"

python3 -m venv /path/to/new/virtual/environment/new_venv

Convenções de nomenclatura do Python

Um dos erros mais comuns entre os desenvolvedores iniciantes de Python é a nomeação inadequada de variáveis, classes, funções etc. As convenções de nomenclatura são elementos essenciais para garantir a legibilidade do código. 

Em Python, a maneira padrão de nomear objetos é explicada na PEP 8. De acordo com as diretrizes, novos módulos e pacotes (incluindo estruturas de terceiros) devem ser escritos de acordo com esses padrões, mas quando uma biblioteca existente tem um estilo diferente, a consistência interna é preferida.

Em geral, você deve evitar usar nomes muito gerais ou muito mundanos. Além disso, os identificadores usados na biblioteca padrão devem ser compatíveis com ASCII, conforme descrito na PEP 3131.

# Bad naming:
data_structure, ríos_españa, dictionary_with_countries_and_capitals
# Good naming:
user_profile, stop_words, global_emissions_df

Abaixo, você encontra uma lista com a convenção de nomenclatura dos objetos mais comuns em Python.

• Pacotes e módulos
• Os nomes de pacotes e módulos devem ser todos em letras minúsculas
• Os sublinhados podem ser usados no nome do pacote e do módulo somente se isso melhorar a legibilidade.
• Classes
• Os nomes das classes devem seguir a convenção UpperCaseCamelCase
• As classes integradas do Python, no entanto, são normalmente palavras em minúsculas
• Variáveis de instância, métodos e funções
• Os nomes das variáveis de instância devem estar todos em letras minúsculas
• Use o sublinhado para adicionar novas palavras às variáveis das instâncias
• As variáveis de instância não públicas devem começar com um único sublinhado
• Constantes
• Os nomes das constantes devem estar totalmente em maiúsculas
• Use o sublinhado para adicionar novas palavras às constantes