Comentários

Eu já falei de comentários, na secção 'Mais sequências'. Contudo existem algumas coisas que podemos fazer com comentários, e vou aproveitar a ocasião para aprofunda-las mais um pouco:

História da versão

É uma boa forma de trabalho criar um cabeçalho de ficheiro, no inicio de cada ficheiro, este cabeçalho poderá fornecer as mais variadas informações. Informações como o dia da criação, o autor, a versão e uma descrição geral do que contém . Este bloco no Python deverá aparecer como um comentário:

#############################
# Módulo:   Receitas.py
# Autor:   A.J.Gauld
# Data:     1999/09/03
# Versão:  Draft 0.4
#
# Descrição: Este módulo fornece várias receitas e vários ingredientes
# que podem ser combinados de outras formas 
# criando-se assim refeições muito interessantes.
#
###############################
# Log:
# 1999/09/01    AJG - Criação do ficheiro
# 1999/09/02    AJG - Pequenas alterações e correcções no código
# 1999/09/02    AJG - Desta vez esta correcto 
# 1999/09/03    AJG - adição de um novo método(cf mudar para Req #1234)
################################
import sys, string, food
...

Comentar código malfeito.

Esta técnica é muito utilizada para isolar uma secção errada de um código. Imagina que escreves um programa que precisa de ler data, processa-la, depois imprimir o resultado e por fim guardar o resultado no ficheiro. Mas imagina também que esse mesmo ficheiro contém uma data que afinal não queríamos processar, portanto, não havíamos de querer guarda-la outra vez. A primeira solução que nos sobe a cabeça seria o de eliminar a parte do código responsável por guardar outra vez a data no ficheiro, garantindo assim que ela não é guardada. Mas uma forma menos radical de tratar o problema seria simplesmente converter essas linhas responsáveis por guardar a data, em comentários, como no exemplo que se segue:

data = readData(ficheirodata)
for item in data:
    resultado.append(calculateResult(item))
printResultado(resultado)
######################
# transformar em comentário até que o bug no calculateResultado seja arranjado
# for item in resultado:
#     ficheiroData.save(item)
######################
print 'Fim do programa'

Uma vez que a falta tenha sido corrigida, ou melhor, uma vez que já tenhas data que penses ser merecedora de ser guardada, simplesmente eliminas os #, tornando essa parte do código activa, mais uma vez.

Strings de Documentação

Todas as linguagens permitem de alguma forma, que cries comentários que documentam o que uma função ou módulo faz, mas poucas linguagens, como por exemplo o Python ou o Smalltalk, vão um passo a frente e permitem que documentes a função ou o módulo por forma com que a linguagem/ambiente de trabalho use essa documentação para fornecer uma ajuda interactiva, enquanto estas a programar. No Python isto é feito usando o estilo das """aspas triplas""":

class Receitas:
    """Como cozinhar carne
    
    pode ser cozinhado com vários outros ingredientes 
    contém um grande número de proteínas benéficas e pode ser cozinhado
    usando várias e diferentes técnicas"""
    
    def __init__(self):
        ...

print receitas.__doc__

Nota: nós podemos depois aceder a string de documentação usando uma forma de especial do print, que é a variável __doc__. Módulos, funções e class todos podem ter uma documentação de string, por exemplo experimenta esta:

import sys
print sys.__doc__

Indentação

Este sem duvida que é um dos temas quentes e dos mais debatidos no mundo da programação. Isto porque ao que parece cada programador/a tem sua ideia já bem formada acerca de como deve ser a indentação de um código. Ao que parece até já foram efectuados estudos acerca do assunto, e chegou-se a conclusão que existem alguns factores verdadeiramente importantes, para além da cosmética - como por exemplo acredita-se qeu uma certa lógica na indentação ajuda a tornar o código mais legível.

A razão para todo este debate é simples. É que na maioria das linguagens de programação, a indentação é puramente uma questão de gosto, e um ajuda ao leitor. ( no Python, não é bem assim, a indentação é realmente importante para o funcionamento do código/programa.) Assim sendo:

 
FOR I = 1 TO 10
    PRINT I
NEXT I

Isto é exactamente o mesmo que:

FOR I = 1 TO 10
PRINT I
NEXT I

Para o interprete do BASIC, tanto faz de uma forma ou de outra. Ele apenas que é apenas mais fácil para nós lermos com a indentação.

O importante, e o que deves manter em mente, é que a indentação deve reflectir a lógica da estrutura do código de uma forma visual. Repara neste exemplo:

XXXXXXXXXXXXXXXXXXXX
    XXXXXXXXXXXXXXXX
    XXXXXXXXXXXXXXXX
    XXXXXXXXXXXXXXXX

O que deve ser mais fácil de ler que o que se segue:

XXXXXXXXXXXXXXXXXXXXX
  XXXXX
    XXXXXXXXXXXX
    XXXXXXXXXXXX
    XXXXXXXXXXXX
  XXXXX

porque dá para perceber logo a primeira que tudo faz parte de um bloco. Estudos mostram que existe uma maior compreensão quando o indentação do do código é uma reflexão da estrutura do bloco. Nos pequenos exemplos que temos visto até agora, isto realmente, não parece muito, porque o código também em si é muito pequeno, mas quando começamos por escrever programas com centenas de milhares de linhas iras certamente dar muita importância ao assunto.

O nome das variáveis

As variáveis que temos usado até agora tem sido sem significado nenhum, isto porque elas na realidade não tinham qualquer significado mesmo, serviram apenas para ilustrar exemplos. Mas regra geral, as variáveis devem mesmo reflectir o que elas representam. Por exemplo na nossa tabuada da multiplicação, nós utilizamos o a variável 'multiplicador', para indicar qual das tabelas que estávamos a imprimir. Isso certamente tem muito mais significado do que simplesmente colocarmos o 'm' como variável, que certamente teria surtido o mesmo efeito tecnicamente falando, e teria dado muito menos trabalho a dactilografar.

Mas a longo termo, ou mesmo a curto quando queremos ler o código, rapidamente vemos que só o m obrigar-nos-ia a ler o código por inteiro para entender qual a função da variável. Então, como podes ver o dar nomes as variáveis é um tentar encontrar um ponto de equilíbrio, entre uma coisa que seja compreensível logo a primeira leitura, e também fácil de escrever. Digo isto para que vocês agora não saiam por aí a por nomes extraordinariamente nas variáveis pensando que seria mais fácil de as interpretar. Por exemplo em vez de multiplicador podíamos por também a_tabela_de_multiplicação_qeu vai_ser_mostrada, mas como podem ver é um nome muito longo, e nem por isso muito mais compreensível que o multiplicador. Percebem onde quero chegar?.

Programação modular

Irei explicar isto mais tarde em mais pormenor, mas por agora contentem-se por eu explicar apenas a teoria que a rodeia, e como podemos utilizar a programação modular para guardar o nosso trabalho- porque no presente momento, todo o trabalho que efectuamos na prompt do interprete é todo perdido assim que saímos do Python, não é verdade?

A prompt '>>>' do Python é extraordinariamente útil para experimentar-nos rapidamente uma ideia e ver se ela realmente funciona ou não, mas assim que saímos do Python perdemos tudo o que foi escrito. A longo prazo nós iremos querer guardar o nosso trabalho, por forma a que possamos utiliza-lo e reutiliza-lo quando quisermos. ou nem que seja apenas para mostrar aos amigos e família dos truques que somos capazes de fazer com um computador. Para fazer isto basta criar um ficheiro de texto com a extensão .py (na realidade, esta extensão é apenas uma convenção, podes utilizar o que quiseres, mas se quiseres saber a minha opinião é melhor que fiques com a convenção). Depois poderás correr os teus programas de uma linha de comando digitando:
$ python receitas.py
Onde receitas.py é o nome do ficheiro onde esta teu programa escrito em Python..

Nota: para utilizadores de sistemas Unix: A primeira linha de um script de Python tem que conter #! seguido do caminho, por completo da localização do Python no teu sistema (podes descobrir isso digitando $ which python na tua linha de comandos)

no meu sistema essa linha que estava falando à pouco tem esta aparência:
#! /usr/local/bin/python
Isto irá permitir que corras o teu programa sem ter que chamar pelo Python ao mesmo tempo:
$ receitas.py
Estas linhas que estivemos a falar não têm efeito nas plataformas Windows/Mac, portanto os utilizadores desses sistemas podem perfeitamente colocar essa linhas, principalmente quando existe uma possibilidade de que os seus programas, possam ser utilizados em maquinas que trabalhem com o Unix.

Nota: para os Utilizadores do Windows: Nos sistemas Windows deves criar uma associação entre os ficheiros que terminem por .py dentro do Explorer. isto irá permitir que corras o teu programa com um simples duplo clique no ícone do ficheiro que o contém. Isto, aliás já deve ter sido feito durante a instalação. Podes verificar se isso realmente aconteceu, procurando por alguns ficheiros .py e tentas um duplo clique neles. Em caso que eles comece a funcionar (mesmo que seja com uma mensagem de erro) isto quer dizer que funciona.

Uma outra grande vantagem em utilizar ficheiros para guardar os teus programas, é que depois poderás edita-los e corrigir os eventuais erros em vez de teres que estar a escrever tudo de novo, e isto então torna-se ainda mais fácil se estiveres a utilizar o IDLE. O IDLE permite mesmo que corras o programa usando o Python como aérea de teste, para isso basta que vás ao menu Run|Edit.

Dito tudo isto, a partir de agora não vou mais mostrar o '>>>' nos meus exemplos, porque estou a assumir que irás criar os teus programas como um ficheiro independente e depois irás testa-los ou no IDLE ou de qualquer linha de comandos (o meu preferido).