안개 낀 함수 감지기: 퍼지기 전에 헷갈리는 코드를 찾아내는 가벼운 의식

어느 정도 성숙한 엔지니어링 팀이라면 다들 비슷한 경험이 있다. 처음엔 “잘 돌아가는” 정도였던 코드가 조용히 시스템의 핵심이 되더니, 몇 년 뒤에는 아무도 손대려고 하지 않는 그것. 함수는 기술적으로는 맞게 동작하지만, 누군가 옆에서 30분 정도 설명해 주지 않으면 제대로 이해하기 어렵다.

처음 그 코드를 읽으면서 느꼈던 미묘한 불편함이 있었을 것이다. 사실 그게 바로 경고 신호였다.

이 글에서는 그 느낌에 이름을 붙이고, 이를 명확한 신호로 바꾼 뒤, 몇 분 안에 적용할 수 있는 가벼운 의식을 정의해 보려 한다. 바로 “안개 낀 함수 감지기(Foggy Function Detector)” 다. 목표는 간단하다. 헷갈리는 코드를 초기에 잡아내서, 아무도 모르게 퍼져나가 기술 부채로 굳어지기 전에 정리하는 것이다.

“안개 낀 함수”란 무엇인가?

안개 낀 함수(foggy function) 는 일종의 코드 스멜이다. 코드도 돌아가고, 테스트도 모두 초록불이지만, 뭔가가 불분명하고, 부서지기 쉬워 보이고, 필요 이상으로 이해하기 어려운 함수다.

안개 낀 함수를 보고 있다는 전형적인 신호는 다음과 같다.

• 무슨 일이 벌어지는지 이해하려고 같은 줄을 여러 번 다시 읽게 된다.
• 논리를 머릿속으로 여러 번 추적해 보고서야 겨우 확신이 생긴다.
• 이 함수가 무슨 일을 하는지 한두 문장으로 요약하기가 어렵다.
• 뭘 건드리면 뭐가 깨질지 확신이 없어, 수정하는 게 망설여진다.

중요한 점은, “안개 낀” 것이 “깨졌다(broken)”는 뜻은 아니라는 것이다. 이 함수는 다음과 같을 수 있다.

• 테스트가 잘 갖춰져 있고
• 프로덕션에서 잘 돌고 있으며
• 눈에 보이는 버그도 없을 수 있다.

하지만 실제 안개처럼, 주변 지형을 가린다. 걸어 다닐 수는 있지만, 속도는 느려지고, 더 조심스러워지고, 넘어질 확률도 올라간다.

다시 말해, 안개 낀 함수는 초기 경고 신호다. 장애로 드러나기 훨씬 전에, 설계나 유지보수성에 문제가 있다는 신호를 보내고 있는 것이다.

왜 안개 낀 함수가 생각보다 더 중요한가

안개 낀 함수는 처음엔 별거 아닌 것처럼 보인다. "일단 냅두자, 잘 돌아가잖아." 하지만 시간이 지날수록 실제 비용을 유발한다.

1. 더 깊은 설계 문제를 숨긴다

코드 스멜은 보통 단독으로 존재하지 않는다. 안개 낀 함수는 종종 다음과 같은 문제를 품고 있다.

• 책임 혼재: 비즈니스 로직과 I/O, 검증, 포매팅 등이 한데 얽혀 있음
• 새는 추상화(Leaky abstraction): 상위 레벨 동작에 하위 레벨 구현 디테일이 스며들어 있음
• 경계 불명확: 원래는 다른 모듈이 맡아야 할 일을 함수가 떠안고 있음

오늘은 단지 이해하기 어려운 함수 하나로 보일지 몰라도, 그 밑에는 점점 진화시키기 힘들어질 설계가 숨어 있다.

2. 모두의 속도를 늦춘다

누군가가 그 함수에 들어올 때마다 인지적 세금(cognitive tax) 을 낸다.

• 읽고 이해하는 데 더 많은 시간
• 변경 영향 범위를 판단하는 데 더 많은 시간
• 자신이 없어 더 많이 테스트하는 데 쓰는 시간

이게 몇 달, 여러 팀원에게 반복되면, 함수 하나 때문에 팀 전체 속도가 꾸준히 깎여 나간다.

3. 코드베이스 전체의 스타일을 조용히 바꾼다

개발자는 눈앞에 보이는 패턴을 따라 한다. 헷갈리는 패턴이라도 “잘 돌아가기만” 하고, 아무도 문제 제기를 하지 않으면 그대로 퍼진다.

• 안개 낀 로직이 복붙되어 새로운 기능에 재사용되고
• 새 모듈이 기존의 불분명한 구조를 그대로 따라 한다

어느 순간, 이 안개 낀 스타일이 팀의 사실상(implicit) 표준이 되어 버린다.

왜 “가벼운 의식”이어야 할까

이 문제를 해결하는 데 거창한 프로세스는 필요 없다. 오히려 품질 관리 프로세스를 과하게 무겁게 만들면, 코드 리뷰가 관료적인 병목으로 변해 역효과가 날 수 있다.

필요한 것은 이런 것이다.

• 가벼울 것 – 몇 분이면 끝나야 한다.
• 반복 가능할 것 – 리뷰마다 쉽게 적용할 수 있어야 한다.
• 일관될 것 – 모두가 같은 관점으로 코드를 볼 수 있어야 한다.

여기서 안개 낀 함수 감지기가 등장한다. 코드에 손을 대거나 리뷰할 때마다 빠르게 돌려 보는 작은 멘탈 체크리스트다. 말 그대로, 어떤 함수가 주의를 더 기울여야 할 대상인지 알아내기 위한 “짧은 가독성 스캔”이다.

이것이 팀 차원의 공통 의식(ritual) 이 되면 다음과 같은 효과를 얻는다.

• 더 빠르고 집중된 코드 리뷰
• 유지보수성 문제의 조기 발견
• 헷갈리는 코드를 이야기할 때 쓸 수 있는 공통 언어

안개 낀 함수 감지기: 간단한 체크리스트

이 체크리스트는 코드 리뷰 중이거나, 인접한 코드를 작업할 때 사용하라. 코드베이스 전체를 한 번에 훑어볼 필요는 없다. 이미 보고 있는 함수에 대해, 그때그때 점진적으로 적용하면 된다.

스스로에게 다음 질문을 던져 보라.

1. 이 함수를 한 문장으로 설명할 수 있는가?

“이 함수는 [무엇을] [누구/무엇] 에 대해 [어떤 조건에서] 수행한다.”

설명이 다음처럼 흘러간다면:

• “음… 기본적으로 A를 하긴 하는데, 또 B도 하고, 경우에 따라서는 C도 하고….”

…너무 많은 책임이 한 함수에 몰려 있을 가능성이 크다.

신호: 함수를 나누거나 헬퍼 함수를 추출하는 것을 고려하라.

2. 흐름을 따라가려면 스크롤하거나 이곳저곳을 계속 왔다 갔다 해야 하는가?

제어 흐름을 이해하기 위해 계속 스크롤을 올렸다 내렸다 하거나, 정의로 점프하고, 파일을 넘나들어야 한다면 이 함수는 아마도 너무 크거나 너무 얽혀 있는 것이다.

가독성 스멜의 전형적인 지표는 다음과 같다.

• 여러 단계로 깊게 중첩된 if/else
• 하나의 함수 안에 뒤섞인 여러 관심사 (예: DB 쿼리, 비즈니스 로직, UI 포매팅이 한 데 섞여 있음)

신호: 더 작은 함수로 추출하고, 조건문을 평탄화(flatten)하거나, 관심사를 분리하라.

3. 이름이 제 역할을 하고 있는가?

함수가 안개 낀 것처럼 느껴지는 이유가 단지 이름 때문인 경우도 많다.

• 애매한 함수 이름 (processData, handleRequest 등)
• 모호한 변수 (flag, data, list 등)
• 사이드 이펙트가 드러나지 않는 이름 (DB에 쓰기도 하는 calculateSomething 같은 함수)

신호: 주석으로 설명해야 할 내용을 좋은 이름 하나로 표현할 수 있다면, 이름을 바꿔라.

4. 숨겨진 상태나 예상 밖의 사이드 이펙트가 있는가?

읽기 쉬운 함수는 다음이 분명하다.

• 입력과 출력이 명시적이고
• 사이드 이펙트가 뚜렷하고 의도적이다.

안개는 다음과 같은 때 끼기 시작한다.

• 예상하지 못했던 공유 상태를 이 함수가 변경한다.
• 전역 설정이나 숨겨진 싱글톤에 의존한다.
• 겉으로 드러나지 않게 로그를 남기거나, 이벤트를 날리거나, 디스크에 쓰는 등의 일을 한다.

신호: 사이드 이펙트를 명시적으로 드러내거나, 순수 로직(pure logic)과 외부 효과를 분리하라.

5. 이 함수는 “변경 이유”가 둘 이상인가?

“앞으로 어떤 이유들로 이 함수를 수정하게 될까?” 라고 자문해 보라.

그 목록에 비즈니스 규칙 변경, UI 수정, 인프라 변경 등 서로 관련 없는 이유가 여러 개 들어가 있다면, 이미 여러 관심사가 섞여 있다는 뜻이다.

신호: 단일 책임 원칙(Single Responsibility Principle)을 적용해, 서로 다른 변경 이유에 따라 함수를 쪼개라.

6. 이 함수가 나를 놀라게 하는가?

“놀람(surprise)”은 강력한 스멜 감지기다. 입력·출력·행동·사이드 이펙트의 어느 부분이라도 읽으면서 “생각과 다르네?” 라는 놀람을 준다면, 이 코드는 최소 놀람 원칙(principle of least astonishment) 을 어기고 있는 것이다.

신호: 이름을 바꾸거나, 로직을 재구성하거나, 위치를 옮겨서, 코드의 실제 동작이 읽는 사람의 기대와 최대한 맞도록 정리하라.

SDLC 안에 감지기를 녹여 넣기

안개 낀 함수를 찾는 작업이 그때그때 기분 내킬 때 하는 활동이어서는 효과가 크지 않다. 진짜 효용을 보려면 팀의 정규 SDLC 거버넌스 안으로 편입되어야 한다.

실제로 통합하는 몇 가지 방법은 다음과 같다.

1. 코드 리뷰의 기본 항목으로 넣기

리뷰 가이드라인에 짧게 한 섹션을 추가하라.

안개 낀 함수 체크(Foggy Function Check)
의미 있는 크기의 함수를 건드릴 때마다:

• 한 문장으로 요약할 수 있는가?
• 책임이 명확히 분리되어 있는가?
• 사이드 이펙트가 명시적인가?

리뷰어가 “잘 돌아가더라도” 안개 낀 것처럼 느껴지는 함수를 과감히 지적하고, 작은 리팩터링을 제안하도록 장려하라.

2. “보이스카우트 룰”을 안개에 적용하기

클래식한 규칙인 “캠프장은 올 때보다 깨끗이 해 놓고 떠나라” 를 코드에도 적용해 보자.

안개 낀 함수에 손댔다면, 이전보다 조금이라도 더 맑게 만들고 떠나라.

이는 대규모 리라이트를 하라는 뜻이 아니다. 아주 작은 일이어도 좋다.

• 변수 이름 하나만 더 명확하게 바꾸기
• 헬퍼 함수 하나만 추출하기
• 의도를 분명히 드러내는 테스트 하나 추가하기

이런 작은 개선이 꾸준히 쌓이면, 안개는 점점 짙어지지 못한다.

3. 안개 낀 영역을 명시적인 기술 부채로 관리하기

함수가 분명히 안개 낀 상태인데, 지금 당장 고치기 어려운 상황이라면:

• 작은 기술 부채 티켓을 만들고
• foggy-function 같은 태그를 붙이고
• 왜 안개 낀 함수라고 느꼈는지 한 줄로 요약해 둔다.

이렇게 하면 막연한 불편함이 눈에 보이고 우선순위를 매길 수 있는 작업 으로 전환된다.

AI 보조 도구를 활용하는 방법

AI 기반 코드 리뷰 도구는 안개 낀 함수 감지기처럼 가벼운 의식을 팀 전체에 퍼뜨리고, 일관되게 적용하는 데 특히 잘 맞는다.

활용할 수 있는 구체적인 방법은 다음과 같다.

1. PR에서 자동 “가독성 스캔” 돌리기

AI 리뷰 도구를 다음과 같이 설정할 수 있다.

• 지나치게 길거나 깊게 중첩된 함수를 표시
• 이름과 실제 동작이 잘 맞지 않는 함수에 플래그를 달기
• 하나의 함수 안에서 여러 관심사가 섞여 있는 경우를 하이라이트

AI는 사람을 대체하지 않는다. 대신, 일관된 1차 필터 로서 잠재적인 안개 낀 영역을 빠짐없이 위로 끌어올려 준다.

2. 리팩터링 후보 자동 제안

어떤 함수가 안개 낀 것으로 표시되면, AI 도구는 다음을 도와줄 수 있다.

• 함수·변수의 대체 이름 제안
• 헬퍼 함수 추출이나 로직 재구성 패턴 제시
• 리팩터링 전·후 예시를 보여줘 개선 효과를 시각화

“나쁜 건 알겠는데, 어떻게 고쳐야 할지 모르겠다”는 상황에서 마찰을 줄여 준다.

3. 체크리스트를 도구 안에 제도화하기

많은 AI 도구는 커스텀 룰이나 프롬프트를 지원한다. 여기에 안개 낀 함수 감지기를 그대로 녹여 넣을 수 있다.

• 체크리스트를 커스텀 분석 프로파일로 만들어 두고
• 새로 추가되거나 변경된 함수에 대해 이 기준으로 평가하도록 요청한다.

이제 이 의식은 사람 머릿속에만 있는 것이 아니라 파이프라인에 내장된 규칙 이 된다.

결론: “정확성”만큼 “명료함”도 1급 시민으로 다뤄라

헷갈리는 코드는 보통 에러로 자신을 드러내지 않는다. 대신, 코드를 읽으면서 드는 미묘한 불편함으로 온다. “이거 잘 돌아가긴 하는데, 건드리긴 싫다”라는 느낌. 그게 바로 조기에 움직일 수 있는 기회다.

안개 낀 함수 는 사소한 귀찮음이 아니다. 더 깊은 설계와 유지보수성 문제에 대한 선행 지표(leading indicator)다. 가벼우면서도 반복 가능한 안개 낀 함수 감지기 의식 을 도입하면, 다음을 얻을 수 있다.

• 이런 초기 경고를 시스템적 문제로 번지기 전에 잡아내고
• 코드 리뷰를 더 빠르고 효과적으로 만들며
• 정확성만큼이나 명료함을 중시하는 팀 문화를 만든다.

AI 보조 리뷰 도구와 결합하면, 코드베이스와 팀 규모가 커져도 이 의식을 일관되게 적용하기가 훨씬 수월해진다.

처음부터 모든 걸 뒤엎을 필요는 없다. 아주 작게 시작하라. 다음 PR에서 함수 하나만 골라 안개 낀 함수 감지기를 돌려 보라. 안개가 낀 것 같다면, 그 안개를 조금만 걷어 내라. 시간이 지나면, 코드베이스가—and 미래의 당신이—그 선택에 감사하게 될 것이다.