Mais sobre as "Regras de Ouro"

Após a divulgação do artigo "As 'Regras de Ouro' do desenvolvimento de software", me pediram para falar mais sobre cada uma, dando exemplos quando possível. Vou tentar atender ao pedido neste artigo.

Não se repita.

Esta regra não se refere apenas a não dizer a mesma coisa duas vezes. Esta regra não se refere apenas a não dizer a mesma coisa duas vezes. Ela está voltada para coisas mais profundas como não armazenar a mesma informação em mais de um lugar.

Por exemplo, imagine que você tem um conjunto de arquivos que deve ser instalado pelo instalador do seu software e, consequentemente, removido na desinstalação. Seria uma quebra desta regra se você fizesse algo do tipo:

:install
  copy a b c d e f <destDir>
:uninstall
  remove a b c d e f from <destDir>

Notaram a repetição de "a b c d e f"? Neste caso para evitar a repetição, a resposta seria usar uma variável. Em outros casos, pode ser mais complicado e exigir até mesmo um gerador de código automático.

Outro caso comum de repetição acontece quando um programador (normalmente novo na equipe, mas às vezes também um antigo e com preguiça de procurar o que já existe no código) inadvertidamente cria uma função para fazer a mesma coisa que uma que já existe e que ele não conhecia.

Outro exemplo, mais sutil:

Comentários descrevendo o que uma parte de código faz. O código em si deveria ser claro o suficiente para explicar o que ele faz (leitores entenderem), além de fazer o que deve (computadores entenderem). Os comentários devem ser usados apenas para informar sobre decisões e aspectos de mais alto nível relacionados ao código. Como está muito bem dito por Andrew Hunt e David Thomas em The Pragmatic Programmer: "bad code requires lots of comments".

Outro exemplo:

Duplicação entre a especificação e o código. Ok, esta é difícil de eliminar, mas num mundo ideal seria legal ter a informação só na especificação e o código sair sozinho. Uma das ideias com UML é poder especificar usando-a e gerar código automaticamente. Bom, a gente sabe o final da história e não preciso falar a respeito. :-)

Não separe o que deve estar junto.

"O que Deus uniu, o programador não separe."

Exemplos:

Documentação de projeto (especificações, etc) devem estar guardadas junto com o código (também devido à regra de manter as coisas perto de onde são usadas - a propósito, todos sabem que as especificações devem ser usadas durante a codificação?).

cpp e h de um mesmo módulo devem estar no mesmo diretório.

Instalador de produto e código do produto devem estar na mesma árvore.

Código do módulo e unit test do módulo devem estar juntos. Aliás, eu particularmente prefiro que o código de unit test esteja dentro do mesmo arquivo que o código de produção do módulo; assim, se diminui o trabalho para criar casos de teste novos ao criar funcionalidades novas e se evita o "esquecimento" de atualizar os testes. Unit test junto do código de produção também facilita a depuração quando aparece um bug, pois facilmente se coloca o módulo suspeito em teste (lembem-se de "O procedimento de correção de bug")

Não junte o que deve estar separado ou coisas que não estão relacionadas.

"O que o programador junta, nem o diabo separa."

Exemplo clássico: O programador precisa fazer uma função que retorna nome e sobrenome, então ele concatena os dois dados numa string e retorna a string, na ilusão de que, se alguém precisar do nome e sobrenome separados (ou em um formato de concatenação diferente...), é só "parsear a string". Não caia nesta ilusão; o correto é retornar os dados separadamente, porque isto é uma interface mais genérica. Ou, o que ainda é melhor no caso de linguagem orientada a objetos: Não ter uma função que retorna o nome e o sobrenome e sim métodos que processam o nome e sobrenome internamente e resolvem todo o problema dentro da classe (exemplo: um serializador para stream).

Guarde as coisas perto de onde elas são usadas.

Aqui a questão é guardar as coisas fisicamente próximas de onde elas são usadas.

Por exemplo, eu tive um cliente que seguidamente me contactava perguntando a data em que alguma versão do software tinha sido liberada e o que tinha sido incluído naquela versão. Para dar uma resposta rápida e exata, eu precisava ter estas informações à mão perto de minha estação de trabalho. Solução: Imprimir um resumo de cada release contendo data, novidades e versão liberada e deixar estas folhas presas na parede na frente da minha mesa - guardadas onde elas seriam usadas.

Outros exemplos:

Se há uma instrução de como desligar o ar condicionado, imprima-a e coloque-a perto do aparelho ao invés de deixá-la na rede da empresa. O mesmo vale para instruções de como fechar porta, fazer café, normas de codificação, etc..

Se há um esqueleto padrão de arquivo fonte, ponha-o bem pertinho de onde os arquivos fonte vão ficar. Junto com os fontes, no sistema de versionamento, num diretório chamado skels, por exemplo.

Guarde todo o material necessário para o seu projeto de software no mesmo sistema de versionamento e faça com que seja fácil (com um comando) baixar tudo quando necessário.

Teste tudo que você faz. 
Teste cedo, teste frequentemente. Se tem 3 linhas, já devia ter sido testado. Se tem um if, já devia ter passado por 2 testes.

O que você testa, funciona de primeira; o que você não testa, dá pau. Precisa dizer mais?

Sistemas de Qualidade de Software

Muito se fala em sistemas de Qualidade de Software (em geral, o pessoal gosta de maiúsculas no nome). Um sistema muito discutido e aplicado no Brasil tem sido o CMM. Infelizmente, poucas vezes se retorna às origens deste sistema para ver de onde surgiu e que problema ele visava resolver. Também poucas vezes se fala a respeito do sucesso ou fracasso deste sistema no mundo de desenvolvimento de SW. Vamos dar uma olhada rápida (e com uma dose de parcialidade) nisto.

O CMM começou com o Departamento de Defesa Americano, como uma ferramenta para avaliação da maturidade de seus fornecedores, em meio a uma crise no gerenciamento e na qualidade do que era recebido. Notem que ele foi concebido como uma ferramenta de avaliação (por conseguinte, externa, para ser usada pelo contratante) e não como uma ferramenta de trabalho das empresas contratadas (que produzem o software). Muito tempo se passou desde então. Hoje em dia, não sei se o DOD ainda usa CMM. Mas sei que muita gente propõe que o usemos como metodologia para produzir software melhor. Pode ser que se consiga, mas até hoje, ainda não presenciei casos de sucesso real. E tenho minhas dúvidas se um modelo originalmente concebido como ferramenta de avaliação realmente é suficiente ou adequado para promover melhorias na qualidade.

Sobre sucessos e fracassos, sempre ouço que a indústria indiana de software tem um grande número de empresas com certificações CMM altas e que isto comprova a importância do CMM. Pode ser. Minha experiência com tais empresas é muito limitada: Resume-se ao fato de que ouvi muitos clientes americanos reclamarem da baixa qualidade do software de companhias indianas, tanto em relação à qualidade intrínseca (correção, desempenho, etc) quanto a prazos. Claro que não devemos generalizar, mas é o que ouvi. A outra experiência que tive foi de uma empresa em que trabalhei e que não tem (ou ao menos não tinha na época) CMM e foi contratada para desenvolver um software que estava há 2 anos nas mãos de uma indiana certificada CMM. Tal software, mesmo após estes 2 anos de trabalho, ainda não era minimamente funcional e apresentava um número elevado de bugs registrados. A decisão tomada logo que minha companhia entrou em cena foi abandonar totalmente a base de código herdada e recomeçar o projeto do zero. Aceitamos o desafio e o projeto foi concluído em aproximadamente 6 meses, com índices de bug baixíssimos (zero críticos, zero graves, três cosméticos) e com funcionalidades mais avançadas que as do projeto original.

E aí me perguntam se eu gosto de Qualidade de Software. Bom, eu prefiro software de qualidade...

LGM

O conjunto básico

E que tal se a gente conversasse hoje sobre o que são as coisas fundamentais num projeto de software?

Todo projeto de software deve conter os itens listados abaixo. Quanto mais cedo eles forem criados, melhor. Recomendo até que eles sejam criados / adicionados na ordem em que os listo.

• Sistema de bug tracking. Exemplos: Bugzilla, Mantis, etc.
  Por que deve ser o primeiro item? Porque bugs ocorrem desde o primeiro dia de trabalho no projeto. Pode ser um erro em algum diagrama, algum problema que um programador encontra no código de outro como resultado de uma revisão, etc. Se ganha muito se isto for registrado de modo centralizado e CONCISO.
  Deve ser um sistema orientado para desenvolvedores, de modo a ajudar não só no controle, mas no processo de correção, ou seja:
• Deve ter, no mínimo, os estados New (não corrigido ainda), Fixed (bug corrigido, correção comitada no source control) e Verified (um release-build que contém a correção foi criado, testado para o bug e não se viu o dito cujo ocorrer novamente). Outros estados, embora não sejam fundamentais, ajudam muito. Exemplos: Assigned (tem alguém corrigindo o bug - isto evita que, em grupos grandes, dois desenvolvedores trabalhem na mesma coisa sem saber), Closed (confirmado pelo usuário que reportou o bug que ele não acontece mais).
•  Os desenvolvedores precisam poder criar entradas neste sistema. Parece mentira, mas tem muita equipe que acha que desenvolvedor não acha bug... Surpresa: Eles acham MUITOS. E normalmente os acham MUITO ANTES que o software entre em uma fase de testes.
• Deve permitir que os desenvolvedores coloquem anotações acerca da investigação das causas do bug no próprio bug report. (As seguintes Regras de Ouro se aplicam: "Não separe o que deve estar junto.", "Guarde as coisas perto de onde elas são usadas."
• Sistema de versionamento de fontes. Exemplos: subversion, git, cvs.
  Deve ser colocado no ar bem cedo, pois devemos ter o histórico desde o início. Muita gente mostra resistência em colocar material no sistema de versionamento antes de ter "algo que funcione". Não é uma boa idéia. Vença a resistência e comece a versionar no primeiro dia.
  Detalhes importantes: 
• Não existe um sistema de versionamento que seja absoluto. Cada método de trabalho casa melhor com um sistema diferente. Não se renda a modismos na hora de escolher. Escolha com a cabeça.
• Um bom versionamento implica em ter tudo no mesmo sistema e na mesma árvore de diretórios. Um comando de checkout único deve baixar todo o material necessário para trabalhar no projeto.
• Build automatizado e integração contínua. Mesmo antes de ter um software funcional (antes de começar a programar), ponha no ar um sistema de integração contínua e automatize o processo de build. O que se quer é que se produza os deliverables do software com apenas um comando e, ao se commitar algo no sistema de versionamento, o sistema de integração contínua faça o build e testes sozinho. Importante: Considero parte dos deliverables a geração de tags no sistema de versionamento, de modo a permitir a recuperação dos fontes usados em cada build.
  Na fase inicial do projeto, ainda não temos código, mas já devemos fazer um sistema automático que gere o pacote de instaladores, documentos (manual do usuário, etc), mesmo que gere um instalador com um executável tipo "return 0", que não faz nada.
• Unit tests. Automatizados, de preferência com possibilidade de rodá-los automaticamente durante o processo de build. Os unit tests devem ser aprimorados ao longo do projeto, por exemplo, quando se encontra um bug (ver O procedimento de correção de bug). Importante: Unit test é feito e rodado pelos desenvolvedores. Pode (e deve, sempre que possível) ser rodado automaticamente no build também; mas o fundamental é que os desenvolvedores possam rodar cada unit test de modo simples e na sua cópia de trabalho dos fontes.
• Número de versão no software. Sem números de versão não tem como ter rastreabilidade do software. Não tem como saber o que foi testado; não tem como saber quando bugs foram corrigidos. Mais detalhes no artigo Identificadores de Versão.
• Testes funcionais. Deve-se ter uma rotina de testes funcionais bem definida e executá-los seguidamente ao longo do projeto. Detalhes importantes: 
• O ambiente de teste (máquinas, dispositivos, etc) deve ser diferente do usado no desenvolvimento. Testes na máquina do desenvolvedor sempre funcionam (a não ser que seja um desenvolvedor muito relapso)...
• Usar sempre o material gerado nos builds automatizados para os testes. Nunca rode testes funcionais oficiais usando material gerado nas máquinas de desenvolvedores.
  

Assinaturas padrão dos operadores de stream

Sempre esqueço da assinatura padrão dos operadores de inserção e remoção do C++. Então resolvi anotar aqui:

std::ostream& operator<<(std::ostream& s, const MyData& data);

std::istream& operator>>(std::istream& s, MyData& data);

Um exemplo de implementação do >>:


istream& operator>>(istream& s, MyDataEnum& data)
{
    int v;
    s >> v;
    
    if (s) //Conversion OK.
        data = MyDataEnum(v);

    return s;
}

Orientação a objetos

Prezados.

O preceito mais básico da Orientação a Objetos é ter dados e operações dentro da mesma unidade lógica (no caso, a classe). Isto também se diz da seguinte forma: Os objetos devem ser responsáveis por si próprios; eles é que devem realizar as operações sobre seus dados internos.

Outro preceito importante é o de encapsulamento de dados ou information hiding. É até anterior à OO, importante também em outros paradigmas de programação. Trata-se de não expor detalhes de como uma entidade é implementada; expor apenas a interface da entidade. Em OO, isto significa, ter poucos (idealmente, nenhum) dados públicos (no sentido semântico de públicos). Um excelente livro sobre programação que eu li, e agora me escapa qual, dizia a este respeito que devemos seguir o conselho ouvido na infância: "Don't show your private parts."

Perco as contas de quantas vezes vejo isto tudo ser deixado de lado. Por exemplo quando fazem algo assim:

class Horario

{

  unsigned hora;

  unsigned minuto;

public:

  unsigned getHora();

  unsigned getMinuto();

  void setHora(unsigned hora);

  void setMinuto(unsigned minuto);

};

main()

{

  Horario t0, t1, t2, t3;

  t0.setHora = 10;

  t0.setMinuto = 10;

  // um pouco mais de código, inicializando tn e fazendo sabe-se mais o que....

  // então imprime alguns t:

  cout << t2.getHora() << ':' << t2.getMinuto() << endl;

  cout << t3.getHora() << ':' << t3.getMinuto() << endl;

}

estão jogando no lixo os preceitos mencionados acima.

O information hiding foi pro vinagre, pois embora os membros não sejam declarados como públicos, semanticamente eles são totalmente públicos: usuários da classe podem fazer o que bem entenderem com eles... Os getXXX e setXXX geram o problema.

Além disso, o preceito básico da OO foi pro espaço também. Notem que as operações (inicialização e "impressão") sobre os objetos estão sendo feitas FORA do objeto (fora da classe).

Melhor seria algo como:


class Horario
{
  unsigned hora;
  unsigned minuto;
public:
  Horario(unsigned h, unsigned m): hora(h), minuto(m) {};
  string paraString()
   {/*converte para string no formato hh:mm, possivelmente usando ostringstream*/};
  //Eventualmente outras operações com Horarios, mas nada de getXXX ou setXXX
 };

main()
{
  Horario t0(10,10);
  Horario t2(5,11);
  Horario t3(23,55);

  // um pouco mais de código, inicializando tn e fazendo sabe-se mais o que....
  // então imprime alguns t:
  cout << t2.paraString() << endl;
  cout << t3.paraString() << endl;
}
Ou, para este caso de "impressão", usando um operador de inserção em stream:
 
class Horario
{
  friend ostream& operator<<(ostream& s, const Horario& h);
  unsigned hora;
  unsigned minuto;
public: 
  Horario(unsigned h, unsigned m): hora(h), minuto(m) {};
  //Eventualmente outras operações com Horarios, mas nada de getXXX ou setXXX
 };

ostream& operator<<(ostream& s, const Horario& h)
{
  s <<  h.hora << ':' << h.minuto;
  return s;
}

main()
{
  Horario t0(10,10);
  Horario t2(5,11);
  Horario t3(23,55);

  // um pouco mais de código, inicializando tn e fazendo sabe-se mais o que....

  // então imprime alguns t:
  cout << t2 << endl;
  cout << t3 << endl;
}

IMPORTANTE!!!!!! Nesta implementação acima, a classe e o operator<< devem estar no mesmo módulo. Ou seja, as declarações de ambas no mesmo .h (horario.h, por exemplo) e as implementações de ambas no mesmo .cpp (horario.cpp, por exemplo). Notem que quebramos um pouco do information hiding nesta implementação, já que o operator<< precisa acessar os dados privados da classe. Quer dizer, a classe não mostra as suas "partes privadas" para todo mundo, mas mostra para os "amiguinhos". Não é o ideal e não me agrada, mas até pode ser aceitável em algumas situações, desde que classe e operador tenham uma "união estável" bem forte e a classe tenha poucos "amiguinhos" (entidades friend).


Eu prefiro uma implementação que inclui o encapsulamento da paraString() e a conveniência do operador<<: Implemento o operator<< chamando o paraString(). Neste caso, a declaração de friend fica desnecessária.

As "Regras de Ouro" do desenvolvimento de software

1. Não se repita.
2. Não separe o que deve estar junto.
3. Não junte o que deve estar separado ou coisas que não estão relacionadas.
4. Guarde as coisas perto de onde elas são usadas.
5. Teste tudo que você faz. (O que você testa, funciona de primeira; o que você não testa, dá pau.)

Para quem se escreve o código-fonte?

Bom, todo (ou quase todo) software que escrevemos possui código-fonte. Mas quando estamos escrevendo este código quem devem ser os "leitores" a quem o dirigimos? Costumo dizer que a resposta dada por um programador para esta pergunta (e o quanto ele aplica a resposta na prática) definem o nível de habilidade deste programador.

Os programadores mais iniciantes ou tacanhos pensam que se deve escrever para que o computador entenda e isto basta. Programadores avançados sabem que se precisa escrever para outros programadores lerem. O que passa desapercebido é que devemos ser claros na nossa escrita e, para isso, devemos ter um vocabulário rico.

Em programação, muitas vezes se pode escrever operações ou expressões diferentes que levam a um mesmo resultado. Usar estas diferenças para expressar melhor o que o programa faz e como o programador pensou na solução é o que eu chamo de ter um vocabulário rico. Aumentamos o nosso vocabulário de programação do mesmo jeito que o de português: estudando, lendo bons textos (no caso, lendo programas), escrevendo com cuidado e pedindo para pessoas experientes revisarem nossos "textos".

Em programação, muitas vezes se usa o termo "idioma" para se referir às peças de vocabulário. Em outros artigos, vou dar alguns exemplos de idiomas em C++, procurando mostrar diferentes idiomas cujos resultados são idênticos para o computador, mas que dizem coisas diferentes para quem lê o código.

Isto me lembra de uma discussão recorrente que tenho com programadores: Eu dizendo "Isto está errado." e o programador respondendo "Mas funciona, logo está certo". Nem tudo que funciona está certo, justamente porque o código pode estar fazendo a coisa certa, mas dizendo a coisa errada. Ou seja, está escrito para o computador, mas não para os leitores humanos.

Vamos a alguns exemplos:

int some16BitVal;

sint_16 some16BitVal;

Mesmo que sint_16 seja um define ou typedef para int, a linha de cima está errada. Quando se escreve int, se está dizendo: preciso de um inteiro que seja o mais eficiente possível nesta arquitetura, mas não me importa o seu tamanho. Se precisamos de tamanho definido, o correto é expressar isto com um tipo.

Outra bem comum: Aproveitar uma constante para dois usos só por que, coincidentemente elas têm o mesmo valor. Se você usa uma mesma constante (e.g. const int mySize=33;) em vários pontos do código, você está dizendo que obrigatoriamente e irrevogavelmente todos aqueles pontos estão ligados e que mudando num todos tem de ser mudados juntos, mantendo todos sempre o mesmo valor.