Software Engineering Architecture

[Software] Cognitive Load(인지 부하) in Code - 실용 가이드

개발팀이 코드에서 불필요한 인지 부하를 줄이는 실전 가이드. 조건문 단순화, 가드 절, 의미 있는 네이밍, 깊은 모듈 설계와 Sonar Cognitive Complexity 활용법까지 한 번에 정리합니다. 온보딩 단축, 리뷰 표준화, 기술 부채 감축 전략 포함.

불필요한 인지 부하를 줄이면 읽기·변경이 쉬워지고 팀 속도가 붙습니다.

인지 부하 핵심 개념

신경과학·교육심리 관점의 정의: 작업을 이해·완수하기 위해 필요한 정신적 노력. Intrinsic/Extraneous/(Germane) 구분이 널리 쓰입니다. Wikipedia
코드 관점의 지표: 사람이 느끼는 이해 난이도에 더 근접한 측정을 지향하는 Cognitive Complexity. SonarSource
아키텍처 관점의 원리: 얕은 모듈을 피하고, 강력한 기능을 단순한 인터페이스 뒤로 숨기는 깊은 모듈을 설계합니다. A Philosophy of Software Design
실천적 모범 사례 아카이브: 조건문 단순화, 조기 반환, 의미 있는 이름 등 실전 예시. GitHub: cognitive-load

코드 레벨 체크리스트

조건문 단순화

복잡한 논리를 의미 있는 중간 변수로 분해합니다.
중첩을 줄이고 조기 반환(guard clauses)으로 해피 패스를 노출합니다.

흐름 제어 평탄화

깊은 if/else 대신 빠른 실패를 적용하고, 예외 처리 경계를 명확히 합니다.

이름과 경계 강화

변수·함수·모듈 이름에 의도를 담아 주석 의존도를 낮춥니다.
모듈 경계를 좁히고 데이터 흐름을 단순화합니다.

얕은 추상화 거부

실질 가치가 없는 래퍼·추상화는 제거하고 실제 복잡도는 내부에서 흡수합니다.

측정과 리뷰 루프

Cognitive Complexity와 정적 분석을 CI에 걸어 PR에서 대화합니다. SonarSource

예시: 조건문 리팩토링

나쁨:

1
2
3
if (val > LIMIT && (isMember || isAdmin) && (isVerified && !isBanned)) {
  proceed();
}

개선:

1
2
3
4
5
6
7
8
9
const isValid = val > LIMIT;
const isAllowed = isMember || isAdmin;
const isSecure = isVerified && !isBanned;

if (!isValid) return;
if (!isAllowed) return;
if (!isSecure) return;

proceed();

아이디어: 의미 있는 중간 변수와 조기 반환은 작업 기억 부담을 줄입니다. 실전 예시는 저장소 정리를 참고하세요. cognitive-load

아키텍처: 얕은 vs 깊은 모듈

얕은 모듈이 많으면 호출자에 퍼지는 인지 비용이 커집니다.
깊은 모듈은 강력한 기능을 간단한 표면 API로 감싸 호출자 부담을 최소화합니다. APOSD

지표의 활용과 한계

Cyclomatic vs Cognitive Complexity: 분기 수만 세는 지표보다 “이해 난이도”에 근접하지만, 최종 판단은 맥락·리뷰어의 근거 있는 설명이 뒷받침해야 합니다. SonarSource

참고 자료