Estilo de Programação

Visão Geral

Perguntas

• Como posso tornar meus programas mais legíveis?

• Como pessoas que programam formatam seus códigos?

• Como programas podem checar sua própria operação?

Objetivos

• Prover boas justificativas para regras básicas de estilo de código.

• Refatore programas de uma página para torná-los mais legíveis e justifique as mudanças.

• Use os standards da comunidade Python (PEP-8).

Estilo de Código.

Um estilo de código consistente ajuda outras pessoas (incluindo nós mesmos no futuro) a ler e entender o código mais facilmente. Código é lido com muito mais frequência que é escrito, e o Zen of Python fala, “Legibilidade conta” (“readability counts). O Python propôs um estilo padrão através de um dos primeiros Python Enhancement Proposals (PEP), a PEP8.

Dois pontos que vale destacar:

• Documente seu código e assegure que suposições, algoritmos internos, inputs e outputs esperados, etc. estejam claros.
• Use nomes de variáveis que sejam claros e informativos.

Siga o estilo padrão do Python em seu código.

• PEP8: um guia de estilo de Python que discute tópicos sobre como nomear variáveis, como indentar seu código, como estruturar os imports, e outras coisas. Aderir a PEP8 torna mais fácil para que outros desenvolvedores Python consigam ler e entender seu código, e entender como suas contribuições devem ser.
• Cheque que o seu código está em conformidade com a PEP8, usando a aplicação pycodestyle e ferramentas como o formatador de código Black, que pode formatar automaticamente seu código para estar em confirmidade com a PEP8 e o pycodestyle (também existe um foromatador para Jupyter Notebook chamado nb_black).
• Alguns grupos e organizaççoes seguem diferentes diretrizes de estilo além da PEP8. Por exemplo, o estilo de código Python da Google faz recomendações ligeraimente diferentes. O Google escreveu uma aplicação chamada yapf que ajuda a formatar o código no estilo deles ou da PEP8.
• Em respeito ao estilo de código, a chave é consistência. Escolha um estilo para o seu projeto, que seja PEP8, o estilo Google, ou alguma outra coisa e faça o seu melhor para assegurar que você e qualquer outra pessoa que você esteja colaborando se atenham a ele. Consistência dentro de um projeto é mais impactante que qualquer estilo em particular. Um estilo consistente vai fazer com que seu código seja mais fácil de ler e entender para outros e para o seu eu no futuro.

Use asserções para checar por erros internos.

Asserções são uma forma simples mais poderosa de assegurar que o contexto que o seu código está sendo executado é como você espera.

def calcular_consumo_hora(consumo, tempo):
    '''Retorna o consumo de uma unidade em megawatts/hora.'''
    assert tempo > 0
    return consumo / tempo

Se a asserção é False, o interpretador Python lança uma exceção de runtime do tipo AssertionError. O código fonte para a expressão que falhou será mostrado como parte da mensagem de erro. Asserções devem conter somente checagens simples e nunca devem alterar o estado do programa. Por exemplo, uma asserção nunca deve conter uma assinalação.

Use docstrings para adicionar ajuda embutida.

Se a primeira coisa em uma função é uma string que não é assinalada diretamente a uma variável, o Python anexa ela à função, tornando-a acessível via a função de ajuda embutida (help()). Essa string que provê documentação também é conhecida como docstring.

def media(valores):
    "Retorna a média dos valores, ou None se nenhum valor é dado."

    if len(valores) == 0:
        return None
    return sum(valores) / len(valores)

help(media)

Help on function average in module __main__:

media(valores)
    Retorna a média dos valores, ou None se nenhum valor é dado.

Strings Multilinha

É comum usar strings multilinha para documentação. Elas começam e terminam com três aspas (sejam simples ou duplas).

"""Essa string se alonga por
múltiplas linhas.

Linhas em branco são permitidas."""

O Que Será Mostrado?

Destaque as linhas no código abaixo que estarão disponíveis como ajuda. Existem linhas que deviam se tornar disponíveis, mas não serão? Alguma linha vai produzir um erro de sintaxe ou erro de runtime?

"Encontra a distância máxima entre múltiplas sequências."
# Isso encontra a distância máxima entre todas as sequências.

def maxima_geral(sequencias):
    '''Determina a distância máxima de edição.'''

    maxima = 0
    for esquerda in sequencias:
        for direita in sequencias:
            '''Evite checar uma sequência contra ela mesma.'''
            if esquerda != direita:
                distancia = editar_distancia(esquerda, direita)
                maxima = max(maxima, distancia)

    # Reportar o valor final.
    return maxima

Documente Isso

Transforme o comentário da função a seguir em uma docstring e cheque que o help mostra ele corretamente.

def meio(a, b, c):
    # Retorna o valor do meio entre os três elementos.
    # Assume que os valores podem de fato ser comparados.
    valores = [a, b, c]
    valores.sort()
    return valores[1]

Solução

def meio(a, b, c):
    '''Retorna o valor do meio entre os três elementos.
    Assume que os valores podem de fato ser comparados.'''
    valores = [a, b, c]
    valores.sort()
    return valores[1]

Pontos-chave

• Siga o estilo padrão do Python em seu código.

• Use docstrings para adicionar ajuda embutida.