C++ 자료형 선택과 별칭¶

상태: 초안 · 적용 범위: 직접 작성하는 C++의 자료형 선택·별칭·강한 타입 도입 판단 · 작성일: 2026-10-06 · 개정일: 2026-10-16

표준 타입을 기본으로 하며 외부 API 전용 구현은 API 타입을 유지한다. 이름 통일로 범위·부호·단위·수명을 숨기지 않는다.

필수·권장·선택은 채택 시의 제안 강도다. C 규칙·언어 버전은 별도 결정하며 일괄 변경하지 않는다. 기본 기능은 C++11, std::byte·std::is_same_v 예제는 C++17 이상이다.

자료형 선택 기준¶

용도	기본 선택	강도·조건
일반 정수 계산	`int`	권장. 필요한 범위를 확인하며 32비트라고 가정하지 않음
논리·실수	`bool`, `float`, `double`	권장. 필요한 정밀도와 API·수학 라이브러리 계약에 맞춤
CPU 객체·메모리 크기, 표준 컨테이너 인덱스	`std::size_t` 또는 컨테이너의 `size_type`	권장. 임의의 개수·GPU 주소·파일 필드로 확대하지 않음
음수가 필요한 차이·상대 오프셋	`std::ptrdiff_t` 또는 필요한 범위의 signed 타입	권장. unsigned 크기끼리 빼고 나중에 캐스트하지 않음
비트 수가 데이터 계약인 정수	`std::int32_t`, `std::uint32_t` 등	필수. 부호와 폭을 계약에 맞춤
연산보다 바이트 표현이 목적인 메모리	`std::byte`	권장. C++17 이상. API가 요구하는 바이트 타입은 유지 가능
외부 API 구조체·출력 변수·전용 상태	해당 API 자료형	권장. 플랫폼과 무관한 인터페이스에 전파하지 않음
분류·상태 값	`enum class`	권장. 임의의 정수나 여러 `bool`로 분류를 표현하지 않음

int·long·float의 폭·IEEE 754 표현을 가정하지 않는다. 정확한 폭의 <cstdint> 타입 제공 여부와 지원 환경을 확인하고 규격을 다른 폭으로 조용히 대체하지 않는다.

std::size_t는 CPU 객체 크기용이며 폭이 플랫폼에 따라 달라져 직렬화에 사용하지 않는다. 인덱스가 불필요하면 범위 for·iterator를 우선하고 필요한 인덱스는 컨테이너의 범위를 보존한다.

권장: unsigned는 비트 마스크·모듈러 연산·크기·외부 규격처럼 이유가 있을 때 선택한다. 값이 음수가 아니란 이유만으로 일반 계산을 모두 unsigned로 바꾸지 않는다. signed·unsigned 혼합 비교와 크기 계산의 안전 조건은 타입 변환과 범위 검사를 따른다.

#include <cstddef>
#include <cstdint>

int retryCount = 0;
bool isReady = false;
float moveSpeed = 3.0f;
std::size_t uploadBytes = 0;
std::uint32_t serializedCount = 0;

표준 선언의 직접 include는 헤더·include 규칙을 따르고 std::로 한정한다. 원래 타입을 유지하는 auto는 허용하지만, 잘못 선택된 계산 타입이나 변환 계약을 숨기는 해결책으로 쓰지 않는다.

외부 API의 자료형을 유지하는 범위¶

권장: API 전용 구현의 지역 변수·상태에도 해당 타입을 유지해 반복 변환을 피한다. 공통 데이터·장면·게임 로직에는 API 별칭·핸들·오류 타입을 불필요하게 전파하지 않는다.

API 출력 인자의 타입과 숫자 변환은 타입 변환과 범위 검사를 따른다.

숫자 타입 교체만으로 외부 의존성이 사라지지는 않는다. 인터페이스 분리 시 헤더·소유권도 검토하고 Windows·GPU 예외는 프로젝트에 기록한다.

자체 별칭을 고려할 시점¶

권장: 새 프로젝트는 표준 타입으로 시작한다. 단순히 std::uint32_t가 길거나 엔진이라는 이유만으로 기본 정수·실수·크기 타입 전체를 다시 정의하지 않는다. 다음 요구가 실제로 생기면 별칭을 검토한다.

계기	별칭이 줄 수 있는 이점	함께 확인할 비용·제약
여러 모듈이 같은 데이터 역할을 반복	`MeshId`, `ByteCount` 등으로 의미를 설명	다른 역할의 값이 타입 수준에서 구분되지는 않음
반복되는 긴 템플릿 타입	읽기 쉬운 이름과 구현 세부 축소	의존성·수명·소유권까지 숨기지 않음
여러 플랫폼·라이브러리를 연결하는 공통 경계	계약에 맞는 표현을 한곳에서 관리	플랫폼별 폭·부호·정렬과 API 변환을 검증
이미 자체 타입을 사용하는 엔진·SDK와 협업	기존 팀·공개 API 표기와 일관성 유지	새 표기와 표준 표기를 무계획하게 병행하지 않음

필수: 별칭 목적·정의 위치·네임스페이스·플랫폼·적용 및 전환 범위·외부 계약을 기록한다. ABI·저장 형식·템플릿 특수화를 확인하고 공개 데이터 폭을 플랫폼마다 바꾸지 않는다.

권장: 새 별칭에는 using을 사용한다(C++11 이상). 타입을 정의하려고 #define을 사용하지 않는다. 별칭 이름은 역할을 설명하며, u32·uint32 같은 기본 타입 축약 표기의 채택 여부는 프로젝트에서 별도로 정한다. 현재 명명 문서에 없는 별칭 전용 표기를 공통 채택으로 간주하지 않는다.

별칭과 강한 타입의 차이¶

필수: 역할을 설명하는 별칭과 서로 다른 값을 구분하는 강한 타입을 구별해 선택한다.

언어 특성: 별칭은 새 타입이 아니며 범위·캐스트·ID 종류 구분을 보장하지 않는다.

#include <cstdint>
#include <type_traits>

using MeshId = std::uint32_t;
using TextureId = std::uint32_t;

static_assert(std::is_same_v<MeshId, TextureId>); // 이름이 달라도 같은 타입

struct MeshHandle
{
    std::uint32_t value = 0;
};

struct TextureHandle
{
    std::uint32_t value = 0;
};

static_assert(!std::is_same_v<MeshHandle, TextureHandle>);

선택: ID·단위 혼동이나 무검증 입력 차단이 필요하면 구조체·클래스·enum class를 검토한다. 값의 유효성에는 생성·연산 제한도 필요하다. 사용처 없는 범용 타입 계층을 미리 만들지 않는다.

별칭은 플랫폼·변환 검사를 없애지 않는다. 과도한 캐스트가 생기면 데이터 계약·경계부터 재검토한다.

외부 데이터와 공개 계약¶

필수: 파일·네트워크·CPU/GPU 공유 구조체는 필드 폭만이 아니라 엔디언·필드 순서·패딩·정렬·버전·논리값 표현을 규격에 기록한다. C++의 bool·std::size_t·포인터·기본 int를 그대로 저장 형식의 필드로 사용하지 않는다. 고정 폭 타입을 선택해도 구조체를 그대로 덤프하거나 셰이더에 복사할 수 있다는 뜻은 아니다.

sizeof·alignof·offsetof는 지원 환경의 배치 검증이며 다른 플랫폼 호환성 보장이 아니다. 형식별 파싱·변환을 사용하고 캐스트 제약을 확인한다. 직렬화·셰이더 배치는 프로젝트 계약으로 관리한다.

적용과 후속 검토¶

기존 코드에는 관련 변경 범위부터 적용한다. 이름만 바꾸는 일괄 수정이나 공개 인터페이스 변경은 별도 작업으로 다룬다.
별칭을 도입해도 중복 표기·전환 비용이 이점보다 크면 유지하지 않는다. 원본 타입의 변경이 영향을 주는 ABI·파일·템플릿·오버로드를 확인한다.
초안 채택 여부, 별칭 축약 표기·네임스페이스, 강한 타입의 생성 정책은 미결정이다. 도구 설정은 이 문서에서 결정하지 않는다.

근거와 출처¶

과거 자료（로컬 참고 자료）의 Core:: 별칭 통일 대신 표준·API 타입과 별칭의 실제 이점을 기준으로 제안했다. 호출별 캐스트와의 차이는 변환 근거를 참조한다. 원본은 보존한다.

아래는 언어 설명의 근거이며 개인 규칙을 자동 채택하는 자료가 아니다. 확인일: 2026-10-06. C++11의 별칭과 C++17의 std::byte·std::is_same_v를 구분한다. C++ 작업 초안의 링크는 계속 갱신되므로 후속 명세의 설명을 이전 언어 버전의 동작으로 확대하지 않는다.

C++ 작업 초안 dcl.typedef — 별칭: 별칭은 새 타입을 만들지 않는다.
C++ 작업 초안 cstdint.syn — 고정 폭 정수: 정확한 폭의 타입 제공 조건을 확인한다.

변경 기록¶

2026-10-16: 반복 설명·중복 예시·배경을 줄여 핵심 규칙과 예시 중심으로 정리했다. 규칙 강도·예외·버전과 채택·초안·미결정 상태는 유지했다.
2026-10-06: 자료형 선택·변환 통합 초안에서 타입 선택·외부 API 타입 유지·별칭·강한 타입·외부 데이터 계약을 분리했다. 변환과 범위 검사는 별도 초안으로 연결하며 기존 채택 규칙과 프로젝트 코드의 타입은 변경하지 않았다.