Headers, .cpp y la Regla de Definición Única (ODR)

Para entender cómo se organiza un proyecto de C++ profesional, primero debemos entender qué es lo que realmente ve el compilador. No compila “proyectos”, compila Unidades de Traducción (TU, por sus siglas en inglés). Una Unidad de Traducción es un archivo de código fuente (un .cpp) junto con todos los archivos de cabecera (.h, .hpp) que incluye tras el preprocesado. El compilador procesa cada TU de forma independiente; no sabe que existe un main.cpp mientras está trabajando en utils.cpp.

Esta arquitectura modular permite una compilación incremental: si cambias un archivo .cpp, solo necesitas recompilar ese archivo y volver a enlazar (link), en lugar de procesar todo el proyecto. Sin embargo, este aislamiento introduce un desafío crítico: la Regla de Definición Única (One Definition Rule u ODR). La ODR dicta que, aunque puedes declarar una entidad (una función, una variable, una clase) tantas veces como quieras, solo puedes definirla exactamente una vez en todo el programa final.

Si intentas definir una función normal (no inline) en un header e incluyes ese header en dos archivos .cpp distintos, el enlazador encontrará dos definiciones idénticas para la misma función al intentar unirlas, y lanzará un error de “multiple definition”. Para solucionar esto, C++ utiliza palabras clave como inline o constexpr, que le indican al enlazador que es aceptable encontrar esa definición en múltiples TUs, siempre que sean idénticas, y que debe elegir una y descartar el resto.

¿Cuándo usar qué? Los headers deben contener declaraciones: firmas de funciones, definiciones de clases/structs, enumeraciones y plantillas (templates). Los archivos .cpp deben contener las implementaciones pesadas: el cuerpo de las funciones no inline y la definición de variables globales. Si necesitas que una función sea visible para todo el mundo pero su cuerpo sea complejo, déjala en un .cpp. Si es una función pequeña o un template que el compilador necesita para instanciar, ponla en el header.

Si violas la ODR, el resultado es el Comportamiento Indefinido (UB). Si las definiciones son idénticas, el enlazador suele resolverlo. Pero si defines void foo() { std::cout << "A"; } en un archivo y void foo() { std::cout << "B"; } en otro, el programa podría compilar y luego comportarse de forma errática, lanzando excepciones extrañas o fallando en producción sin razón aparente.

El siguiente ejemplo simula cómo se dividiría un módulo real en un proyecto. Para que sea un único archivo compilable, utilizaremos inline donde sería necesario en un header para evitar errores de redefinición.

// --- MOCK_HEADER.h (Representación lógica de un archivo de cabecera) ---

#include <iostream>
#include <string_view>
#include <span>

// 1. Definición de clase: Se puede poner en el header porque el 
// compilador necesita conocer el tamaño y los miembros para instanciarla.
class DataProcessor {
public:
    DataProcessor(int id) : id_(id) {}
    
    // Declaración de un método no-inline. La implementación va en el .cpp
    void process(std::span<const int> data);

    // 2. Función inline: Se define en el header. El 'inline' permite 
    // que se incluya en múltiples TUs sin violar la ODR.
    inline int get_id() const { return id_; }

private:
    int id_;
};

// 3. Plantilla (Template): Las plantillas deben estar en el header.
// El compilador necesita ver la implementación para generar el código
// específico para cada tipo cuando se instancie.
template <typename T>
T multiply_by_two(T value) {
    return value * 2;
}

// 4. Declaración de variable externa: 'extern' dice al compilador: 
// "Esta variable existe en algún lugar, confía en mí".
extern int global_version;

// --- MOCK_IMPLEMENTATION.cpp (Representación lógica de la implementación) ---

// Implementación del método de la clase
void DataProcessor::process(std::span<const int> data) {
    std::cout << "Procesando " << data.size() << " elementos...\n";
    for (int val : data) {
        std::cout << val << " ";
    }
    std::cout << "\n";
}

// 5. Definición de la variable global: Se define en un solo .cpp.
int global_version = 42;

// --- main.cpp (Punto de entrada) ---

int main() {
    int values[] = {10, 20, 30, 40};
    
    DataProcessor processor(101);
    
    // Uso de método de clase (no-inline)
    processor.process(values);

    // Uso de función inline (definida en header)
    std::cout << "ID: " << processor.get_id() << "\n";

    // Uso de template (instanciado en el main)
    std::cout << "Double 21: " << multiply_by_two(21) << "\n";

    // Uso de variable externa
    std::cout << "Version global: " << global_version << "\n";

    return 0;
}

Para compilar este ejemplo como un archivo único (simulando la unión de todos los archivos):
g++ -std=c++20 -Wall -Wextra -Wpedantic -o example example.cpp

Desglose del concepto

• DataProcessor::process: Es una función miembro no inline. En un proyecto real, su cuerpo vive en el .cpp. Esto mantiene los tiempos de compilación bajos y oculta la implementación. El compilador solo sabe que existe gracias a la declaración en el header.
• DataProcessor::get_id: Marcada como inline. Si esta función no fuera inline e incluyéramos su cabecera en main.cpp y en otro archivo extra.cpp, el enlazador daría error de “multiple definition” al intentar crear el ejecutable final.
• multiply_by_two<T>: Al ser un template, no es una función real hasta que se usa con un tipo concreto (como int). El compilador genera el código en el main.cpp en el momento en que ve multiply_by_two(21). Por eso, la implementación debe estar en el header; si estuviera en un .cpp, el compilador no podría verla al compilar el main.cpp y el enlazador fallaría.
• global_version: Usamos extern en la cabecera. Esto es crucial. Si pusiéramos int global_version = 42; directamente en el header, cada archivo .cpp que incluya ese header intentaría reservar espacio para esa variable, causando un error de duplicidad. extern es una declaración, no una definición.

El error frecuente

Un error clásico en equipos que migran de proyectos pequeños a sistemas grandes es definir funciones no inline directamente en los headers para “ahorrar tiempo”.

// --- error.h ---
// ERROR: Definición de función normal en un header
void log_message(const char* msg) {
    std::cout << "[LOG]: " << msg << std::endl;
}

Si file_a.cpp incluye error.h y file_b.cpp también lo incluye, el compilador generará el objeto de ambos archivos con la misma función log_message. Al intentar enlazarlos, obtendrás un error de multiple definition.

Para arreglarlo, tienes dos opciones:
1. Mover la implementación al .cpp (lo ideal para funciones complejas).
2. Marcar la función como inline (si la función es muy pequeña y quieres permitir que el compilador la optimice mediante inlining).

Si intentas “engañar” al compilador con funciones con el mismo nombre pero cuerpos distintos en diferentes archivos, el compilador no siempre te avisará, pero el comportamiento de tu programa será impredecible.

N° 110