Boas práticas de programação

Ao escrever seu código, o programador deve sempre ter em mente que seu script deve ser legível tanto para si quanto para outros que possam ler e colaborar.

Além disso, ao manter boas práticas de programação, seu código possui maiores chances de produzir menos erros. Se porventura, após a conclusão do seu projeto, ocorrer um erro em sua execução, será mais fácil de identificá-lo.

Já foi mencionado anteriormente sobre os comentários no código aqui neste link. 

Em Python, há também outra maneira de comentar seu código utilizando  docstrings. Uma das diferenças que ocorre entre docstring e comentários é que nos comentários utiliza-se o símbolo # para cada linha, enquanto que na docstring utiliza-se apóstrofos triplos (''') antes e após os comentários, permitindo escrever em uma ou mais linhas.

Exemplo de comentário com #:

# comentário em uma linha

# este comentário está
# em duas linhas

Para comentários maiores que uma linha, precisaremos de # para cada nova linha.

Exemplo de comentário com ''':

'''Isto aqui é um docstring que permite escrever longas explicações
em mais de uma linha'''

As docstrings passam pelo mesmo processo que os comentários, tudo o que está escrito entre os sinais ''' é ignorado na execução do código. Isto é, nada é mostrado ao usuário.
Então, qual a diferença entre os comentários utilizando #?
Quando se comenta com docstring, estas documentarão o objeto a que estão se referindo. Logo, se estamos documentando uma função em Python, o usuário poderá ter acesso à docstring a partir da função embutida help().

Exemplo:

'''Este programa só mostra Olá mundo!'''

# comentário que não aparecerá no help do Python
print('olá mundo!')

Escreva o programa acima na janela de script do Python e o salve como olamundo.py na pasta do Python. Ele será nosso módulo.

Agora, importe seu programa olamundo.py na janela do IDLE digitando:

import olamundo

Se após o comando nada acontecer, é porque ocorreu tudo certo (nenhum erro foi mostrado).
Utilize a função help() no seu módulo recém importado:

help(olamundo)

O IDLE deverá mostrar o seguinte resultado:

Help on module olamundo:

NAME
    olamundo - Este programa só mostra Olá mundo!

FILE
    c:\users\nomedousuario\appdata\local\programs\python\python36-32\olamundo.py

Observe que a primeira linha do código acima indica que foi utilizada a função help no módulo olamundo e na linha NAME mostra o nome do módulo e a docstring escrita. Por último, o caminho do arquivo importado.

Perceba também que a linha de comentário #comentário que não aparecerá no help do Python não foi retornada. Repetindo - esta é a principal diferença entre um comentário e docstring.


----------

Agora que sabemos a diferença de estilos de comentários, quais são as boas práticas de programação?

As docstrings são comumente utilizadas no início do script, como um cabeçalho, e dentro de classes, métodos e funções. Elas permitirão o usuário compreender o que o programa e cada bloco dele é capaz de realizar - assumindo que este código foi de um outro programador que fez uso das boas práticas de programação.

Vamos para um código um pouco mais elaborado.
Exemplo:

'''Este programa realiza cálculos aritméticos'''

# minhas variaveis
a = 5
b = 6

def soma(a,b):
    '''Retorna a soma entre a e b'''
    pass

Após criar o programa acima, salve-o como aritmetica.py e depois importe-o como módulo através do IDLE do Python utilizando o comando import:

import aritmetica

Agora vamos ver a documentação do nosso módulo. Escreva os comando com help():

help(aritmetica)

O resultado deverá ser parecido com o mostrado abaixo:

Help on module aritmetica:

NAME
    aritmetica - Este programa realiza cálculos aritméticos

FUNCTIONS
    soma(a, b)
        Retorna a soma entre a e b

DATA
    a = 5
    b = 6

FILE
    c:\users\nomedousuario\appdata\local\programs\python\python36-32\aritmetica.py

Nosso módulo possui o docstring cabeçalho explicando do que se trata o programa e também a função soma com a docstring indicando que a função realiza a soma entre as duas variáveis.

----------

Espaçamento entre Linhas

Outra dica de boas práticas de programação é utilizar muito bem as linhas de espaçamento a fim de facilitar a visualização dos blocos do código.

Exemplo de código mal espaçado:

a = 1
b = 2
def soma(a,b):
    return a+b
def subtracao(a,b):
    return a-b
def multip(a,b):
    return a*b
def divisao(a,b):
    return a/b

Exemplo com boas práticas:

# variáveis
a = 1
b = 2

def soma(a,b):
    return a+b

def subtracao(a,b):
    return a-b

def multiplicacao(a,b):
    return a*b

def divisao(a,b):
    return a/b

Veja como há uma maior fluidez na leitura de um código bem espaçado. Vemos que as funções são distintintas.


Espaçamento entre Caracteres

Um bom espaçamento facilita a leitura e a manutenção do código caso haja algum erro.

Exemplo de mau uso:

# variáveis
a=1
b=2

print(a+b)
print(b-a)
print(a-b*a)

Exemplo de bom uso do espaçamento entre caracteres:

# variáveis
a = 1
b = 2

print(a + b)
print(b - a)
print(a - b * a)

Com estas dicas, a programação se tornará mais fluida e legível.


Referências e Links Úteis:

Comentários e docstrings - https://pt.wikibooks.org/wiki/Python/Conceitos_básicos/Comentários_e_docstrings
Docstring em Python - https://en.wikipedia.org/wiki/Docstring
Liang, Y.D. Introduction to Programming Using Python. Pearson, 2013.