Por que não escrevemos código no ficheiro de cabeçalho?

O código nos ficheiros de cabeçalho (.h ou .hpp em C++) não deve ser colocado pelas seguintes razões:

1. Violação da regra de uma única definição (One Definition Rule - ODR). Quando vários ficheiros .cpp incluem um ficheiro de cabeçalho que contém código executável, este será definido mais do que uma vez, levando a um erro de ligação (definição múltipla). A exceção são as funções inline e os modelos de classes/funções, que devem ser definidos em cada módulo de tradução onde são utilizados.

   // exemplo.h
   int g_counter = 0; // Variável global - violação da ODR
   
   void my_function() { // Função - violação da ODR
       // código
   }
   
   inline void my_inline_function() { // função inline - exceção
       // código
   }
   
   template<typename T>
   void process(T value) { // modelo de função - exceção
       // código
   }
   

2. Aumento do tempo de compilação. Cada inclusão de um ficheiro de cabeçalho faz com que o compilador processe novamente o seu conteúdo. Colocar código em ficheiros de cabeçalho aumenta a carga de trabalho do compilador, atrasando o processo de construção do projeto, especialmente em projetos grandes.

3. Complexidade na manutenção e testes. O código disperso em ficheiros de cabeçalho torna-se menos modular. Isto dificulta o teste de componentes individuais e a sua alteração independente.

4. Risco de ciclos de inclusão (include loops). Uma organização incorreta das inclusões com código em ficheiros de cabeçalho pode levar a dependências cíclicas e problemas de compilação.

Nos ficheiros de cabeçalho, geralmente declara-se:

• Classes (definições, mas não implementações de métodos)
• Funções (protótipos)
• Variáveis globais (usando extern)
• Constantes
• Modelos de classes e funções (definições completas)
• Funções inline (definições completas)
• Tipos de dados (struct, enum, typedef, using)
• Espaços de nomes (namespace)

A implementação do código (corpo das funções, definições de membros estáticos de classes e variáveis globais) é colocada nos ficheiros de implementação correspondentes (.cpp).