인지 부하가 중요함

• 이 오픈소스 프로젝트는 소프트웨어 개발에서 인지 부하를 줄이는 다양한 방법과 사례를 체계적으로 정리함
• 불필요하게 복잡한 코드, 구조, 추상화가 개발자의 생산성을 저해하고 유지보수 비용을 증가시킴
• 모듈은 “작고 얕은 것”보다는 심플한 인터페이스와 강력한 기능을 가진 깊은 구조가 바람직함
• 과도한 추상화, 프레임워크 의존, DRY 원칙의 남용은 오히려 인지 부하를 가중시키는 원인임
• 가장 좋은 아키텍처는 단순하고 새로운 개발자도 빠르게 이해할 수 있게 하는 코드베이스임

---

프로젝트 요약 및 의의

이 깃허브 오픈소스 자료는 소프트웨어 개발의 핵심 원칙 중 하나로 ‘인지 부하(cognitive load)’에 초점을 맞추고 있음. 이 저장소의 가장 큰 특징은, 팀 규모나 기술 트렌드와 상관없이 개발자가 실제로 마주치는 복잡성의 근원을 다양한 사례와 해결법으로 정리한다는 점임. 다른 베스트 프랙티스 위주의 자료들과 달리, 심리적·인지적 부담까지 고려해 실질적으로 유지보수와 신규 팀원의 온보딩에 강점을 보임.

서론

• 우리가 개발 현장에서 듣는 트렌디한 개념이나 베스트 프랙티스들은 실제 개발에서 자주 실패 경험이 있음
• 실제 현업에서 느끼는 혼란과 그로 인한 시간/비용 손실의 핵심 원인은 높은 인지 부하임
• 개발자는 코드를 작성하는 것보다 이해하고 읽는 데 더 많은 시간을 소요함
• 본문은 불필요하게 발생하는 인지 부하(Extraneous Cognitive Load) 를 줄이는 실용적 방법에 집중함

인지 부하란

• 인지 부하란 개발자가 작업을 완료하기 위해 머릿속에 담아야 하는 정보량을 의미함
• 평균적으로 한 번에 4개 정도의 ‘청크 정보’(조건, 변수 값 등)만 단기 기억에 담을 수 있음
• 인지 부하가 임계치에 다다르면, 이해와 개발 속도에 큰 저하 발생

인지 부하의 유형

• 고유 인지 부하(Intrinsic) : 작업 자체의 본질적 어렵기에서 기인. 줄일 수 없음
• 불필요한 인지 부하(Extraneous) : 정보 제공 방식, 구조 설계, 불필요한 패턴 등 인위적 복잡성에서 기인. 적극적으로 줄일 수 있음

실용적 예시와 개선 방안

복잡한 조건문

• 여러 조건이 중첩된 코드는 각 단계별로 머릿속에 기억해야 할 내용이 늘어나 인지 부하 증가
• 해결: 의미 있는 중간 변수를 도입해 각 조건의 목적을 명확히 나눔

중첩 if문 vs Early Return

• 중첩된 if문보다 이른 반환(Early Return) 패턴이 전제조건 기억 부담을 줄임
• ‘행복한 경로’(happy path)만 기억하면 되게끔 만들어 작업 기억 공간을 해방함

상속 구조의 부작용

• 깊은 상속 체계(예: 클래스A → 클래스B → 클래스C …)는 코드를 이해하는 데 많은 계층 정보를 한 번에 기억해야 해 인지 부하 폭등
• 해결: 컴포지션 우선, 불필요한 상속 대신 조합(합성) 활용

너무 많은 얕은 모듈/함수

• 80개의 얕고 작은 클래스보다는 몇 개의 강력하고 심플한 인터페이스를 가진 딥 모듈이 더 유지보수 용이
• 예시로 UNIX I/O의 단순한 인터페이스(open, read, write, lseek, close)를 듦

무분별한 '단일 책임 원칙' 오해

• ‘한 가지 일만 한다’의 모호한 해석이 오히려 얕고 불분명한 추상화 양산
• 실질적으로는 ‘한 명의 이해관계자에게 책임을 진다’로 해석해야 비즈니스 연관성 이해 및 인지 부하를 줄일 수 있음

마이크로서비스 남용

• 너무 많은 얕은 마이크로서비스는 각 서비스 관계와 연동 정보를 계속 머릿속에 담아야 해 인지 부하 및 디버깅/런칭 비용 증가
• 초기에는 완성도 높은 모놀리식 구조가 오히려 유지보수에 유리

언어의 과도한 기능/옵션

• 언어 자체의 수많은 신기능(특히 C++ 등)은 오히려 ‘왜 이렇게 구현됐는지’를 추적하며 기억 부담 누적
• 비즈니스와 무관한 부차적 인지 부하 남발

HTTP 상태코드와 비즈니스 로직 매핑

• HTTP 상태코드(401, 403, 418 등)와 내부 비즈니스 의미의 임의 매핑은 팀원 모두가 외워야 함
• 개선: 자기 설명적 문자열 코드(예: "jwt_has_expired")로 일관되게 전달

DRY(Do not repeat yourself) 원칙의 남용

• 복잡한 코드베이스에서 무리하게 중복 제거만 하면 강한 의존성이 생겨 인지 부하와 변경 비용이 오히려 증가
• 로컬에서 ‘약간의 복사’가 더 낫다는 Rob Pike의 명언 인용

프레임워크 의존과 Layered Architecture의 폐해

• 프레임워크의 ‘마법’ 구조 깊이 의존 시 신규 개발자는 내부 로직 파악에 장시간 소요
• 추상화 레이어 누적은 실제 문제 추적 시점에 인지 부하 폭등
• 근본적 원리(Dependency Inversion, Info Hiding, Cognitive Load control)에 집중해야 함

도메인 기반 설계(DDD)의 오해

• DDD의 핵심은 문제 영역 분석으로, 폴더 구조/패턴 집착은 오히려 주관적 해석 및 인지 부하 유발
• ‘Team Topologies’ 같은 프레임워크가 인지 부하 분할에 더 효과적임

친숙함 vs 단순함

• 친숙함이 단순함과 동일하지 않음. 익숙해서 가벼워진 것이지 실제로 구조가 쉬운 것은 아님
• 신규 입사자가 40분 넘게 혼란을 느낀다면 코드 개선 필요 신호

실제 성공/실패 사례

• Instagram처럼 단순 모놀리식 아키텍처로도 높은 확장과 유지보수 경험 가능
• “정말 똑똑한 개발자”가 복잡한 구조를 만든 회사는 오히려 실패 경험 빈번
• 모든 개발자가 쉽게 읽고 빠르게 온보딩 할 수 있는 구조가 생산성 향상에 핵심적 역할을 함

결론

• 본질적 작업을 넘어선 불필요한 인지 부하는 모든 개발 주체에게 해악
• 가장 좋은 코드는 미래의 다른 개발자와 자신이 최대한 빠르게 이해할 수 있는 코드
• “똑똑해 보이는” 구조보다 평범하고 직설적인 해결책이 유지보수와 팀 생산성에 장기적으로 더 유리함

참고/후기

• Rob Pike, Andrej Karpathy, Elon Musk, Addy Osmani, antirez(Redis 개발자), 유명 개발자들의 의견도 인용됨
• Chromium, Redis, Instagram 등 실제 대규모 사례와 일치하는 시사점 제시
• 단순함과 명료함, 인지 부하 절감이 곧 소프트웨어 지속 가능성의 핵심임

이 오픈소스 프로젝트의 가치

• 수많은 소프트웨어 설계 서적이나 패턴들이 놓치는 현실적 개발자 경험과 실천적 사례 중심 자료
• 개발자 온보딩, 아키텍처 리뷰, 장기적 유지보수 등 다양한 팀에 즉각적 실질 도움 제공
• ‘인지 부하’라는 명확한 틀로 코드를 되돌아볼 수 있는 체크리스트 역할

[GN⁺]

Hacker News 의견

• A Philosophy Of Software Design by John Ousterhout란 책에서 가장 큰 깨달음을 얻음, 이 주제에 관한 최고의 책이라 개발자라면 꼭 읽기를 추천함. 핵심은 소프트웨어 설계에서 복잡성을 최소화하는 것이 목표가 되어야 한다는 것인데, 여기서 복잡성이란 '변경하기가 얼마나 어려운가'로 정의되며, 이 '어려움'은 코드를 이해하는 데 드는 인지 부담에 의해 결정됨

  • 문제는 어떤 규칙도 결국 판단력, 경험, 직관을 대체할 수는 없음. 모든 규칙은 논쟁의 도구가 될 수 있고, 아키텍처 논쟁에선 절대 이기지 못한다는 것임. 이 글이 좋은 이유는 필요 없는 사람은 이미 알고 있고, 정말 필요한 사람한텐 이해되지 않을 것이기 때문임. 결국 이건 기술적인 문제가 아니라 사람과 문화의 문제임. 아키텍처는 결국 사람과 문화에서 따라오는 것임. Rob Pike와 Google이 있으니 Go가 나오는 것처럼, 그냥 책 한 권 읽는다고 Go 같은 언어가 탄생하진 않음

  • DRY 원칙(중복을 피하라)은 실제로 어플리케이션을 충분히 이해하고 여러 버전을 만든 후에나 고려해야 할 원칙이라고 생각함. 처음엔 오히려 반복하면서 먼저 문제 공간을 이해하고, 두 번째 버전에서 유지보수 가능하도록 고민해야 함. 세 번째 버전쯤에야 비로소 DRY를 적용해도 된다고 봄

  • 이 책을 Jeff Bezos에게 돈을 안 주고 구하기 너무 힘듦. 혹시 저자 John과 아는 사람이 있다면 이 문제를 꼭 좀 알렸으면 좋겠음. 캠퍼스 서점에도 없었고, 로컬 서점이나 Powell’s서점도 구하지 못했음

  • 오랜 시간 완벽한 소프트웨어 해법을 찾는 걸 포기함. 그 누구도 완벽하게 정리한 사람은 없는 것 같음. 결국 우리가 가진 최고의 무기는 사람들의 지혜와 경험임. 맥락이나 산업, 팀이 너무 달라서 숫자나 법칙으로 딱 정의할 수 없음. 결국 나는 설계에서 '엉망진창'과 '아름다움' 사이의 균형을 찾는 걸 목표로 삼음. 가장 어려웠던 점은 사업은 불확실하면서 소프트웨어는 확정적이라서, 비즈니스 요구사항이 항상 바뀌고 이를 컴퓨터 시스템의 경직성에 맞추기가 어렵다는 점임. 요즘엔 코드를 바꾸려 할 때 직접 불편함이 느껴져야만 리팩토링 시도함. 그때도 최소한의 정리만 함. 이렇게 여러 번 반복적인 리팩토링을 하다 보면 새로운 패턴이 생겨나고, 그걸 추상화로 뽑아내기도 함

  • 이 책이 바로 그 주제의 최고임. 해당 글도 이 책에서 영감을 받았음. 저자 John과도 글 내용에 대해 한두 가지 대화 나눴음

• 다른 사람들의 인지 부담을 줄이는 코드를 만드는 능력은 매우 희귀하고 어려운 스킬임. 능력이 있어도 꾸준한 노력이 필요함. 결국 개발자는 핵심 아이디어를 압축해서 본질만을 드러내고, 반드시 필요한 복잡성만 노출하는 것임. 실제로 이런 걸 잘하는 경우를 거의 못 봄

  • 정말 잘 만든 코드는 결국 사람들이 '이게 원래부터 쉬운 문제였나?' 하는 착각을 하게 만듦. 반면에 복잡함이 눈에 보이는 '집 카드' 같은 코드는 노력의 흔적으로 인정을 받고 승진까지 이어짐

  • 이런 건 인터페이스나 UX/인터랙션 디자인에도 똑같이 해당됨. 개발자들은 일반인보다 인지 부담을 훨씬 잘 감당하지만, 기술자 아닌 사람들이 잘 쓰게 만들려면 개발자 본인의 직관에서 벗어나야 해서 난이도가 매우 높음. 일반사용자가 직관적으로 복잡한 문제를 풀 수 있도록 도구를 설계하는 것은 정말 어려움

  • 대부분의 추상화는 요건 변경 시 잘 살아남지 못함. 내가 좋아하는 프레임워크는 영원히 완벽한 추상화층을 만들 수 없음을 알고 '탈출구'를 의도적으로 제공함. (예: 웹UI 프레임워크에서 html element의 direct reference 제공 등) 미래를 완벽히 예측할 수 없다는 현명함이 중요함

  • 실제로 이런 스킬은 많은 회사에 필수라기 보단 보너스 요소임. 주요 코드베이스를 보면 쉽게 알 수 있음

• 나는 스스로 '괴짜 성향의 스마트 개발자' 중 하나라고 생각함. 추상화 구축을 좋아하는 편임. 요즘 업계가 'if-문 더미 아키텍처'로 돌아가는 게 신기하면서도 걱정됨. 단순해보여서 이해하기 쉽고, 주어진 티켓만 닫으면 되기 때문에 많은 사람들이 좋아하는 이유를 알겠음. 대부분의 개발 프로세스가 if문 더미에 의존하고, 이 방식이 일정 수준 이상의 케이스에서는 실제로 잘 동작함. 심지어 개인정보 대량 유출 같은 일이 터져도 책임지는 사람도 별로 없음. 그런데 문제는 이보다 나은 대안이 있는지 모르겠다는 것임. 화려한 추상화나 멋진 아키텍처도 실제로 코드의 정합성을 높여주진 않는 듯함. 특히 기업 환경에서는 비즈니스 로직 소유자들이 로직에 신경을 거의 안 쓰기 때문에 조심스레 예쁜 추상화를 만들 수가 없음. 결국 '주문은 한 주소로만 배송된다' 같은 요구가 있다가 갑자기 '큰 고객이 여러 주소로 배송해달랬다'처럼 바뀌고, 이런 혼돈 속에서 버그 없는 추상화란 건 존재하기 어려움. 현실적으로 기업용 소프트웨어에서 if-문 더미가 최선 아닌가라는 생각까지 듦

  • 'if-문 더미' 방식이 최선인가라는 질문에, 현실의 대형 소프트웨어 아키텍처를 다룬 Big Ball of Mud 논문과 요약 글을 추천함. 실제 시스템은 항상 진화하며, 처음엔 '진흙덩이'로 시작해 부분별로 개선하다가 다시 변화가 오면 아름답던 추상화도 무너짐. 핵심은 마치 작은 마을이 도시로 성장하듯 도메인 모델링, 적당한 추상화, 그리고 필요한 파괴적 변화의 조합으로 시스템을 성장시키는 것임

  • 이런 소프트웨어에서도 멋진 추상화를 만들 수 있지만, 비즈니스 로직이 개입되는 순간부터는 유지가 어려움. 추상화가 제대로 남아있는 부분은 주로 제품적인 요소, 예를 들어 인증, 권한, 로그, 데이터베이스, 미들웨어, 인프라 등임. 비즈니스 내부 로직이 추상화에 영향을 주기 시작하면 결국 다시 엉망이 됨. 어떤 곳에서는 아예 비즈니스 사람이 직접 논리를 관리하도록 했는데, 이건 테스트도 어렵고 이해도 불가, 심지어 시뮬레이션조차 불가능해졌음. 결국 운영자가 필요해서 junior 개발자가 그래픽 툴로 코드 쓰는 상황도 발생. 여러 번 리라이트해도 2~3년 후엔 항상 뒤죽박죽이 됨

  • 비즈니스 사람들이 비즈니스 논리를 구현자에게 완벽히 설명하는 건 절대 불가능함. 그들 스스로는 이해하더라도, 코딩 관점에서 표현할 수 없기 때문임. 오히려 구현자 중 최소 한 명은 정말 뼛속까지 사용자를 체험해야 제대로 알 수 있음. 현실적으로 기업들은 부서 분리를 강요하고, '비즈니스 로직'은 신경 안 쓰는 구역이 되어 결국 if문만 조작함

  • 현실, 즉 비즈니스 그 자체가 이미 if문 더미인 게 핵심임. 문제나 도메인이 명확하게 기술적이거나 일반화될 수 있으면 추상화로 if문을 줄일 수 있겠지만, 도메인 자체가 혼돈이라면 추상화도 결국 '유연성'을 기본으로 넣을 수밖에 없음. 모순이 오히려 기능이 될 수도 있음

  • Codex CLI와 같은 툴로 놀아보면, 이 툴은 버그를 만나면 항상 특정 케이스를 위한 if문 패치를 생성함. 패턴을 직접 알려주고 새 추상화를 요청하지 않는 한, 계속해서 '휴리스틱'이라 부르는 if문을 추가함. 특정 타입의 버그 10개에 대해 10개의 패치가 만들어지고, 11번째 비슷한 버그가 나오면 당연히 작동하지 않음. Codex가 제시한 해법이 if문 반복의 집합임

• 완전히 모르는 프로젝트에서 수정을 요청받는 상황은 현실에서 얼마나 흔한가 의문임. 프로젝트 이직이 정말 잦지 않다면 2년에 한 번 정도임. 경험 부족이 아닌 진짜 어려운 문제에 집중하는 게 더 낫다고 생각함

• Microsoft 개발자 조직에서 8년 일하며 초창기 엔지니어 유형 모델링이 매우 유용했음. 세 가지 페르소나가 있었는데, 나중엔 더 복잡한 프레임워크로 대체됨. 그래도 원래 페르소나는 지금까지도 내 경력에서 타 엔지니어와 효과적으로 소통하는 데 큰 도움이 되었음.

  • Mort: 실용주의 엔지니어, 비즈니스 결과가 최우선. if문 더미라도 빠르게 동작하면 충분.
  • Elvis: 혁신이 우선, 최신 기술 사용, 자신의 천재성이 알려지길 원함. 새로운 프레임워크 도입과 불안정한 코드, 가시성과 혁신에 집착.
  • Einstein: 성능, 우아함, 기술적 정확성에 집착. 코드의 일관성과 기술적 완성도를 더 중시함. 현실적으로 모든 엔지니어는 이 셋의 혼합체임. PR과 설계 리뷰 몇 번이면 주성향을 대충 파악할 수 있음

  • 여기에 Amanda라는 엔지니어 유형도 있어야 한다고 생각함. 20년간 자신과 남의 엉망진창 코드를 리뷰하다 보니, 이제는 코드가 무엇보다 '사람이 읽기 위함'임을 체화함. 그런 Amanda들로만 팀 꾸리고 싶음

  • Mort는 실용주의자, Einstein은 완벽주의자, Elvis는... 사실상 프로젝트에 해악인 존재라고 생각함. 조금은 동기부여가 되지만 이상적인 팀은 Mort와 Einstein을 잘 혼합하는 것임. 필요한 만큼만 단순하게 만들면서도 충분한 정확성을 확보해야 유지보수가 괴롭지 않음. 오히려 Mort에게 장기 프로젝트를 맡겨 두면 언젠간 Einstein처럼 신경쓰기 시작함. 여담이지만, 최근 자동 코딩 에이전트들은 Mort 성향이 너무 강해서, 내가 오히려 Mort로서 관리를 해야 할 지경임

  • 페르소나는 좋은 도구임. 내 경험상 시간이 지나면서 잘못된 지름길로 변질됨. Elvis는 실제론 내부 정치용 용어였고, Goodhart의 법칙처럼, 논리적으로 맞는 것처럼 보이니 모두 논쟁에서 쓰려고 해서 결국 유용성이 저하됨. Alan Cooper가 옛날에 Visual Basic 개발과 함께 페르소나 개념 도입했었음. 나와 다른 관점, 즉 과학자와 펌웨어 개발자는 서로 가치관이 다름을 이해하는 것이 중요함. 관련 도서

  • 최고의 엔지니어는 세 가지 성향을 프로젝트, 상황, 개인적 목표에 맞게 조절할 수 있는 사람이라고 봄. 역할에 따라 필요한 비중이 다름. 예를 들어 컴파일러 최적화에는 Einstein과 Mort가 더 필요하고, 게임 엔진 같은 코드는 비율이 다름. 각 특성이 정확한지는 논쟁의 여지가 있지만, 모두가 시간에 따라 다르게 작동해야 한다는 것이 핵심임

  • 이 방식엔 경계가 필요하다고 봄. 사람을 너무 단순하게 범주화하면 부당하고 영구적인 낙인찍기가 될 수 있음. 경험상, 오히려 경영진들은 Elvis보다 Mort를 선호함. 실제 해법은 리더십과 관리에 있다고 봄. Mort에게 코드 품질 기준을 요구사항에 포함시키면, 조금 느리더라도 괜찮은 결과물을 낼 수 있음. Elvis는 제한을, Einsteins는 실용적으로 마감 조건을 명확히 지정해야 함. 이 방법은 인간의 복잡성을 간과하는 한계가 있음

• AI가 소프트웨어 산업에 해가 될까봐 우려함. AI는 인간의 한계를 가지지 않으니 굉장히 복잡하고 읽기 힘들지만 동작하는 코드를 쓸 수 있고, 그러다 결국 망가졌을 때 아무도 고칠 수 없을 것임. 그래서 주니어 엔지니어들에게 AI에만 의존하지 말고 코드베이스의 특성을 익히라고 권장함. 그렇지 않으면 스스로 코드를 작성할 수 있는 능력을 잃게 됨

  • AI는 동작이 멈춰도 다시 고칠 수 있으니 이런 주장은 설득력이 없다고 생각함

  • 내 경험상 AI의 코드를 반드시 이해할 수 있을 때까지 계속 단순화해 달라고 요구함. 복잡한 방식이면 더 쉽게, 쓸데없는 외부 라이브러리를 쓴다면 빼달라고 하고, stdlib로 해결하거나 이미 있는 의존성만 사용하게 함. AI는 내 대신 코드를 쓰는 것이지, AI 자신을 위한 게 아님

  • 오히려 AI 덕분에 저수준 설계에 드는 인지 부담이 줄어서 상위 아키텍처 고민에 더 집중할 수 있으니, 소프트웨어 품질이 올라갈 수도 있다고 생각함

• 글에서 언급한 '스마트 개발자 특유의 습성'에 대해, 저자가 자신이 작성하거나 자신 스타일로 쓰인 코드만 이해할 수 있다는 의미처럼 보임. 하지만 인지 부담을 줄이는 진짜 비결은 읽지 않아도 되는 코드의 양을 최소화하는 데 있음. 강한 경계와 명확한 API가 변경 작업을 쉽게 만들어 주며, 핵심은 전체 코드가 아니라 잘 정의된 인터페이스에서 파생된 복잡성만 신경 쓰면 되는 것임. '스마트 개발자'의 특이점이 오히려 표면적인 문제임

  • 마이크로서비스 개념의 최대 장점이 바로 이 부분임. 두 팀이 오직 API로만 소통하고, schema 같은 도구로 경계를 엄격하게 정의하면, 변화에 엄청나게 보수적으로 변하고 사전에 아주 깊이 생각하게 됨. 바뀌지 않길 바라는 지점에 인위적인 마찰을 기술적으로 삽입하는 효과라고 봄

  • 디버깅하면서 많이 느낀 건, 콜스택 상에서 직접 디버깅해야 하는 코드에 과하게 최적화된 부분이 있으면 매우 피곤하다는 것임. 그래서 특정 부분만 함수로 뽑아내고 커밋을 나누면, 원치 않는 코드 변경도 쉽게 롤백 가능하고 코드 집중도가 높아짐. PR에서는 한 번에 올라오겠지만, 그래도 경계가 명확하면 훨씬 나음

  • 개발자들은 대체로 '계약과 인터페이스'로 사고하는 걸 잘 못함. 내부 구현이 아닌, 겉으로 드러나는 약속만 보도록 해야 함. 코드를 읽지 않아도 이해 가능한 게 목표임. 만약 내 코드를 이해하려고 직접 들여다보게 만든다면 그건 실패임

  • API가 아무리 명확해도 내부 코드는 쉽게 이해되지 않을 수 있음. 겉으론 잘 동작하는 것처럼 보여도, 실제로는 그 내부까지 파고 들어가야 하는 경우가 많음

• 이 글이 내 경험을 아주 잘 요약해줘서 너무 좋음. 공식적으로 배운 대부분의 프로그래밍 방법론은, 남이 내 코드를 읽어야 하는 순간 역효과가 남. Rust와 C++처럼 복잡하게 숨기는 코드는 힘들고, C처럼 템플릿 6겹에 코드를 숨길 수 없는 구조를 보면 오히려 마음이 놓임

  • 내 경험과 통한다니 반가움. 나도 같은 이유로 C를 좋아했고, 최근에는 Golang으로 넘어가서 이쪽의 단순함이 마음에 듦

• 코드 접근성을 일급 시민처럼 다뤄야 한다는 말이 정말 와닿음. 규칙은 지침으로 삼고, 정말 실력자는 코드가 읽히기 쉽도록, 언제 규칙을 깨거나 보완할지 맥락에 따라 판단하는 능력을 갖추는 것임. 결국 코드의 인지적 부담과 절충점을 직감할 수 있는 능력이 중요함. 중복이든 추상화든, 6개월 후의 나를 포함한 다음 사람을 항상 염두에 두어야 함. 규칙을 하나 더 만들자는 요구에 대해선, 그 자체로 또 다른 문제의 반복임. 기본 가이드라인 이후로는 tacit knowledge 즉, 경험에서 나오는 암묵적 지식임. 시간이 쌓이면 어느 코드가 좋고 나쁜지를 스스로 느끼게 됨. 최종적으로는 직접 느끼는 수밖에 없음

  • 코드 접근성의 본질에 동의하지만, 작성자는 germane overhead(수신자의 인지적 자원 소비)를 간과했다는 게 아쉬움. 결국 코드 접근성을 높이기 위해선 intrinsic, extraneous, germane 세 가지 오버헤드를 모두 고려해야 함

• "왜"를 문서화하라는 말이 있지만, 난 "왜"와 "무엇"을 분리하기가 힘들어서 둘 다 기록함. 가장 안 좋은 코멘트는

  x = 4 // assign 4 to x 
  

  이런 식임. 코드와 주석을 섞으면 읽기도 힘들고 맥락 전환이 심함. 대신

  // 왜 이걸 하는지, 무슨 일을 할 건지
  setup();
  t = setupThing();
  t.useThing(42);
  t.theWidget(need=true);
  ...
  

  이런 식으로 주석과 코드를 명확히 나누는 게 좋음. 그래도 "무엇"이라도 쓰는 게 아무것도 없는 것보다는 훨씬 낫고 인지 부담 줄임

  • 이런 형식의 주석은 대부분 유지가 어렵고, 구현이 1년에 5번은 바뀌니 금방 낡아서 혼란스러워짐. 최근 프로젝트에서는 정말 어려운 로직과 최상위 문서만 남기고 대부분 주석 제거함

  • 두 가지(why/what) 모두 문서화해야 할 때가 있다고 생각함. 때로는 이유를, 때로는 동작 내용을 명확히 해야 함. 요즘엔 주석의 가치가 과소평가된다고 봄. 모든 줄에 주석 붙일 필요는 없지만, 대다수의 '셀프-문서화 코드'도 그다지 읽기 쉽지 않음

  • 요즘엔 어떤 내용을 코드에 남기고, 어떤 것을 디자인 문서/기술문서에 남길지 결정하는 것이 가장 어렵다고 느낌. 내 결론은, 코드 내 주석은 비직관적이거나 숨겨진 의도를 설명하는 데 쓰는 것이 좋다는 것임. 예: "이걸 메모이즈하는 이유는 X 때문임"

  • ChatGPT 스타일의 x=4 주석에 웃음이 남. 대신 제안한 방식의 단점은, 주석이 코드와 불일치하게 낡아질 위험이라는 점임. 코드를 수정할 때 주석도 꼭 갱신해야 함

  • 난 교육상 프로그래머가 아니라 물리학자라서, 주석을 달 때마다 위 방식으로 바꿔보려 노력 중임. 학생 시절엔 성적을 위해서는 무조건 주석을 많이 다는 게 관행이었음