인지부하가 핵심입니다(Cognitive load is what matters) 를 읽으며 - 3편

2025.12.14 - [잡다한 지식] - 인지부하가 핵심입니다(Cognitive load is what matters) 를 읽으며 - 1편

인지부하가 핵심입니다(Cognitive load is what matters) 를 읽으며 - 1편

2025.12.14 - [잡다한 지식] - 인지부하가 핵심입니다(Cognitive load is what matters) 를 읽으며 - 2편

인지부하가 핵심입니다(Cognitive load is what matters) 를 읽으며 - 2편

 

1편에서는 저의 경험담과 인지부하에 대한 간단한 설명을,

2편에서는 인지부하의 일부 사례를 소개해드렸습니다.

 

이번 포스팅에서는 2편 포스팅에서 모두 소개하지 못한 사례를 소개해드릴려고 합니다.

 

이번에도 https://github.com/zakirullin/cognitive-load 글을 참고하여 작성하였습니다.

 

비즈니스 로직과 HTTP 상태 코드 (Business logic and HTTP status codes)

프론트와 백엔드 엔지니어는 HTTP 상태코드에 대해 합의하고 사용합니다.

- 401: 만료된 JWT 토큰 
- 403: 접근 권한 부족
- 418: 차단된 사용자

 

추후에 QA 엔지니어가 테스트할 때 403 에러를 만났다면, 이것이 무엇을 의미하는지 바로 알 수 있을까요?

토큰이 없는 것인지, 권한이 낮은 것인지, 아니면 특정 조건이 부족한건지 직관적으로 알기 어렵습니다.

그래서 QA 엔지니어는 이 에러의 원인을 찾기 위해 코드를 뒤지거나 문서를 찾아봐야 합니다.

 

{
    "code": "jwt_has_expired"
}

 

위와 같이 코드 안에 직접적으로 설명하는 것이 더 효율적입니다.

내부적으로는 '인증' 이라는 용어를 쓰더라도, 응답 메시지에는 '로그인' 같은 더 직관적이고 쉬운 용어를 사용하는 것이 좋습니다.

 

과거에는 메모리가 부족해서 정보를 최대한 압축해야 했습니다.

하지만 현재는 그렇지 않습니다. 퍼포먼스를 고려해야하는 상황을 일반적으로 마주치기 힘듭니다.

상대방이 이해하기 쉽도록 정보를 충분히 보내주세요.

 

DRY 원칙 남용 (Abusing DRY principle)

Do Not Repeat Yourself(반복하지 마세요)

코드는 재사용 되게 짜는 것이 좋으나, 반복을 제거하려고만 하면 구성 요소 간에 긴밀한 결합이 발생할 수 있습니다.

 

동일해 보이는 코드라도 변경되는 이유와 시점이 다르다면,

그것은 중복이 아니라 우연히 닮은 것입니다.

 

프레임워크와의 긴밀한 결합

장고같은 프레임워크로 프로그래밍을 시작하는 사람이 많습니다.

프레임워크는 수많은 복잡한 로직을 내부에 숨겨두었기 때문에,

우리는 빠르게 기능을 구현할 수 있습니다.

 

하지만 비즈니스 요구사항이 프레임워크가 정해둔 표준 방식을 조금이라도 벗어나는 순간,

프레임워크는 족쇄가 되버립니다.

그러므로 프레임워크는 가능한 '라이브러리'처럼 필요한 기능만 쓰도록 하는 것을 추천합니다.

 

계층형 아키텍처

의존성 역전이나 추상화 등 다양한 기법들은 파일의 수를 늘리고 계층을 추가시킵니다.

코드의 깊이가 깊어지면 디버깅은 어려워집니다.

로직의 흐름을 쫓기 위해 수많은 파일을 끊임없이 넘나들어야 하기 때문입니다.

이 과정에서 발생하는 잦은 문맥 전환(Context Switching)은 개발자의 인지 부하를 가중시킵니다.

 

[프로그래머 연차에 따른 복잡도 풍자](https://github.com/zakirullin/cognitive-load/blob/main/img/complexity.png)

 

* OOP, Design Pattern, Abstraction Interface 가 나쁘다는 것이 아닙니다.

* 필요한 곳에 필요한 것을 쓰지 않는다면, 쓰지 않는 것만 못할 수 있습니다.

* 고급 개념과 테크닉을 사용하려면 주변 동료도 동일한 수준으로 올라와야합니다. 이는 맞는 기법이더라도 아닐 수 있습니다.

* 아주 유명한 이론이더라도 나만 알고 쓴다면, 상대방에게는 엄청난 인지부하로 다가 올 수 있습니다.

 

도메인 주도 설계 (Domain-Driven Design)

도메인 주도 설계(DDD)는 "문제 영역" 에 대한 훌륭한 접근방식입니다.

개발자, 도메인 전문가 및 비즈니스 담당자는 하나의 통일된 언어를 사용하여 효과적으로 소통하게 돕기 때문입니다.  

 

하지만 많은 경우 DDD 는 '문제 해결' 보다는

특정 폴더 구조, 서비스, 레포지토리 같은 '구현 방법'의 규칙으로 오해합니다.

각자가 DDD 를 해석하는 방식은 주관적일텐데 구현은 하나의 방식이 되버립니다.

 

코드의 구조가 아니라 비즈니스 도메인으로 생각하기

 

간단한 주문 취소 기능 하나를 만드는데,

"DDD" 를 적용한다고 요청 객체, 로직 수행, DB 저장, 이벤트 발행 등 수많은 파일로 쪼개 놓는다면 어떨까요?

동료들은 "도대체 왜 이렇게 복잡하게 만들었지?"라고 생각할 것입니다.

 

DDD 가치는 맥락을 분리하는 것입니다.

DB 입장에서는 주문 취소가 DB 에서 데이터를 지우는 행위일지라도,

도메인 관점에서는 배송 전의 '철회'와 배송 후의 '환불'로 나뉩니다.

코드로는 order.withdraw(), order.refund() 로 나눠질 수 있습니다.

"돈을 돌려주고 상태를 바꾼다" 라는 것은 같지만 비즈니스적 의도와 맥락이 다릅니다.

DDD 에서는 이를 우아한 중복(Accidental Duplication) 이라고 합니다.

지금은 같아 보여도 미래에는 서로 다른 방향으로 나아갈 확률이 큽니다.

 

나중에 시스템이 커지면 한 사람이 모든 기능을 파악할 수 없습니다.

DDD 를 통해 도메인의 경계를 잘 나눠 각 팀이 특정 기능을 담당하도록 하면,

각자 자신의 영역만 파악하면 되니까 인지부하를 감소시킬 수 있습니다.

 

익숙한 프로젝트의 인지 부하

익숙함과 단순함은 같은 단어가 아닙니다.

익숙함과 단순함은 비슷한 느낌을 주지만, 그 느낌을 받는 본질은 다르기 때문입니다.

• 익숙함: 나에게는 쉽지만, 처음 온 사람에게는 미로입니다. 매일 다니던 복잡한 골목길을 눈 감고도 찾아가는 것과 같습니다. 
• 단순함: 나에게도 쉽고, 처음 온 사람에게도 쉽습니다. 누가 봐도 알기 쉽게 쭉 뻗은 큰길입니다. 

[익숙함과 단순함의 인지부하] (https://github.com/zakirullin/cognitive-load/blob/main/img/mentalmodelsv15.png)

 

개발자들은 자신이 짠 코드가 '익숙'해지면, 그 코드가 '복잡'하다는 사실을 잊어버립니다.

그래서 "이게 왜 어려워?"라고 생각하게 되죠.

 

저는 개인적으로 과외를 하면서 많이 느꼈습니다.

저는 가르치는 내용을 계속해서 접했기 때문에 너무 당연하다하고 넘어갔는데,

학생들은 그 내용을 처음 접하다 보니 이해하는데 시간이 꽤 걸렸습니다.

남을 가르쳐보면서 자신이 지식의 저주에 빠지진 않았는지 되돌아보는 것도 좋다고 생각합니다.

 

그래서 우리는 신입 개발자와도 많은 이야기를 나누어야 합니다.

신입 개발자는 아직 '익숙'하지 않기 때문에,

무엇이 '복잡'한지 바로 알아채고 우리에게 알려줄 수 있습니다.

 

오픈소스의 거대한 코드들은 한번에 만들어진게 아닙니다.

조금씩 조금씩 계속해서 추가된 것입니다.

이 과정에서 코드를 오랫동안 개발해온 사람들은 코드에 익숙해집니다.

복잡한 로직도 당연하게 보입니다.

하지만 코드가 건강해질려면 익숙함에서 벗어나야합니다.

새로운 기여자를 위해, 유지보수를 위해 코드는 계속해서 단순하게 정리되어야 합니다.

 

"머릿속에 그려야하는 지도가 너무 커지지 않은가?"

"단순함을 잘 유지하고 있는가?"

이 질문에 대한 답은 새로운 개발자의 온보딩 과정에서 찾을 수 있습니다.

코드를 보는데 40분 이상 혼란스러워한다면 코드에서 개선할 부분이 있다는 것입니다.

 

마지막

 

인지 부하를 줄인다는 것은 기술의 문제이기도 하지만,

결국 "남의 입장에서 생각하기" 라는 단순한 태도의 문제입니다.

남을 배려하고 많이 생각하는 사람이,

동료를 위해 가장 친절하고 단순한 코드를 작성하기 때문입니다.

 

 

결국 우리가 함께 일하고 싶어 하는 '좋은 사람'이, 사실은 가장 '유능한 개발자'인 이유입니다.