Desenvolvimento Código Aberto

Imagine o seguinte cenário:

Uma fabrica de software que esta há vários anos no mercado e desenvolve aplicativos para Windows em 5 linguagens de programação  diferentes entre elas: C++, Java, C#, Delphi e Python. A fabrica conta com 5 equipes com 10 desenvolvedores cada. Acontece que ao longo dos anos cada sistema sempre teve sua própria autonomia de desenvolvimento havendo muitos códigos redundantes entre elas. O novo CEO da empresa resolveu  projetar um framework* único em C++  pretendendo poupar horas de programação de código entre as equipes.

O gerente de projeto responsável pelo framework* baixa no gerenciador de código fonte o seguinte código enviado pelo  líder da equipe de Python:

 cidade = raw_imput("Entre uma cidade")
 while cidade[-1]==" " :
         cidade = cidade[:-1]
 temp=raw_input("Entre uma temperatura in farenheit: ")
 temp = float (temp)
 temp = (temp - 32.0) * (100.0/180.0)
 temp = round(temp,3)
 temp = srt(temp)
 print "Na "+cidade+" é "+temp+ " graus celsius!"

Há um monte de problemas com este código fonte. Um rápido exame e nenhuma informação é revelada sobre qual dos nossos funcionários escreveu este código. Qual é o nome do arquivo? O que ele faz? À primeira vista, estamos perdidos. Este código iria receber uma nota 10?

O código fonte é devolvido e reformulado por uma desenvolvedora da equipe,  seguindo as melhores praticas de programação de software e retorna assim:

#Alicia P. Hacker
#Fah_para_Celsius.py

#coleta a cidade
cidade = raw_imput("Entre uma cidade")

#trunca espaços em branco
while cidade[-1]==" " :
cidade = cidade[:-1]

#coleta a temperatura
temp=raw_input("Entre uma temperatura in farenheit: ")

#converte string para float
temp = float (temp)

#Converte graus farenheith para graus celsius
temp = (temp - 32.0) * (100.0/180.0)

#Arredonda para três casas decimais
temp = round(temp,3)

#reconverte string para concatenação
temp = srt(temp)

#imprime o resultado
print "Na "+cidade+" são "+ temp + " graus celsius!"

Podemos ver claramente o nome de Alicia e o nome do seu arquivo. Além disso, ela comentou bem as linhas do seu programa. Este código iria receber uma nota 10.

Você deve ser como Alicia! Você deve comentar onde você puder colocar comentários que explicam o que está fazendo, e se você está fazendo algo complicado ou original não se esqueça de explicar bem.

Uma boa meta é ter um comentário a cada 1-4 linhas de código. Certifique-se de não só documentar o que o código está fazendo, mas, quando você começa a escrever um código mais avançado, você deve documentar o que foi deixado intencionalmente de fora, otimizado, testados e rejeitados, etc, basicamente, qualquer decisão de projeto que você faz.

Uma atividade simples que muitas fabricas de software ignoram  mas que possibilita o entendimento de códigos complicados com mais rapidez , encontrar facilmente os bugs, melhorar a comunicação entre equipes de desenvolvimento, facilidade de visualização além de embelezar o código(code beautifier).

* Framework é uma abstração que une códigos comuns entre vários projetos de software provendo uma funcionalidade genérica