유지보수 가능한 코드 작성: 설명적인 네이밍의 힘

Source: Dev.to

설명적인 이름 지정의 중요성

유지보수 가능한 코드를 작성할 때 가장 간과되기 쉬우면서도 중요한 측면 중 하나는 변수, 함수, 클래스에 설명적이고 의미 있는 이름을 선택하는 것입니다. 짧고 암호화된 이름이나 약어는 몇 번의 키 입력을 절약할 수 있지만, 시간이 지나면서 이해하고 유지보수하기 어려운 코드를 초래하는 경우가 많습니다. 명확한 이름은 목적과 기능을 즉시 전달하여 코드를 자체 문서화(self‑documenting)하게 만듭니다.

변수 이름 지정 가이드라인

• 데이터의 의도를 전달하는 이름을 선호하세요. 예: userAge 혹은 totalSalesAmount → 일반적인 x 나 data 같은 이름보다 좋습니다.
• 추가적인 맥락 없이도 이해할 수 있도록, 지나치게 축약된 형태는 피하세요.

함수 및 메서드 이름 지정

• 함수가 무엇을 하는지를 설명하는 이름을 선택하고, 어떻게 하는지는 설명하지 마세요.
  • ✅ calculateTotal – 수행하는 동작을 명확히 나타냅니다.
  • ❌ doMath – 모호하고 정보가 부족합니다.
• 적절할 때는 동사‑명사 구조를 사용하세요(예: fetchUserProfile, validateInput).

클래스 이름 지정

• 클래스가 모델링하는 엔터티나 개념을 나타내는 이름을 선택하세요.
  • ✅ ShoppingCart – 목적을 즉시 떠올리게 합니다.
  • ❌ DataHandler – 애매하고 일반적입니다.
• 클래스 이름은 단수형 명사 중심으로 유지하세요.

일관된 이름 지정 규칙

• 프로젝트 전반에 걸쳐 하나의 네이밍 스타일을 채택하세요—camelCase, snake_case, PascalCase 중 하나를 선택합니다.
• 일관성은 인지 부하를 줄여 개발자가 코드베이스를 탐색하고 이해하기 쉽게 만듭니다.

기억하세요: 코드는 작성되는 것보다 훨씬 더 자주 읽힙니다. 명확하고 설명적인 이름에 시간을 투자하면 코드가 더 유지보수 가능하고 자체 문서화되는 효과를 얻을 수 있습니다.