O que colocar nos cabeçalhos:
- O conjunto mínimo de diretivas
#include
que são necessárias para tornar o cabeçalho compilável quando o cabeçalho é incluído em algum arquivo de origem. - Definições de símbolos do pré-processador de itens que precisam ser compartilhados e que só podem ser executados por meio do pré-processador. Mesmo em C, os símbolos do pré-processador são mantidos no mínimo.
- Encaminhar declarações de estruturas necessárias para tornar as definições de estrutura, protótipos de função e declarações de variáveis globais no corpo do cabeçalho compilável.
- Definições de estruturas de dados e enumerações que são compartilhadas entre vários arquivos de origem.
- Declarações de funções e variáveis cujas definições serão visíveis para o vinculador.
- Definições da função inline, mas tenha cuidado aqui.
O que não pertence em um cabeçalho:
- Diretivas
#include
gratuitas. Aqueles gratuitos incluem causar recompilação de coisas que não precisam ser recompiladas, e às vezes podem fazer com que um sistema não possa ser compilado. Não#include
um arquivo em um cabeçalho se o próprio cabeçalho não precisar desse outro arquivo de cabeçalho. - Símbolos de pré-processador cuja intenção poderia ser realizada por algum mecanismo, qualquer mecanismo, diferente do pré-processador.
- Muitas e muitas definições de estrutura. Divida-os em cabeçalhos separados.
- Definições em linha de funções que exigem
#include
adicionais, que estão sujeitas a alterações ou que são muito grandes. Essas funções inline devem ter pouco ou nenhum fan-out, e se elas tiverem fan-out, elas devem ser localizadas para coisas definidas no cabeçalho.
O que constitui o conjunto mínimo de #include
declarações?
Isso acaba sendo uma questão não trivial. Uma definição TL; DR: Um arquivo de cabeçalho deve incluir os arquivos de cabeçalho que definem diretamente cada um dos tipos usados diretamente ou que declaram diretamente cada uma das funções usadas no arquivo de cabeçalho em questão, mas não devem incluir mais nada. Um ponteiro ou tipo de referência C ++ não se qualifica como uso direto; referências para frente são preferidas.
Há um lugar para uma diretiva #include
gratuita, e isso está em um teste automatizado. Para cada arquivo de cabeçalho em um pacote de software, eu automaticamente gero e, em seguida, compilo o seguinte:
#include "path/to/random/header_under_test"
int main () { return 0; }
A compilação deve estar limpa (ou seja, livre de quaisquer avisos ou erros). Avisos ou erros referentes a tipos incompletos ou desconhecidos significam que o arquivo de cabeçalho em teste possui algumas diretivas #include
ausentes e / ou declarações encaminhadas ausentes. Note bem: só porque o teste passa não significa que o conjunto de diretivas #include
seja suficiente, e muito menos o mínimo.