2장: 개발 시간을 줄여주는 이름 짓기와 주석 쓰기

[fkdl0048]

2장: 개발 시간을 줄여주는 이름 짓기와 주석 쓰기

네이밍 컨벤션, 이유를 알고 쓰자

개발자의 가장 큰 고민은 이름 짓기

개발자는 한 프로젝트만 해도 매우 많은 내용의 이름을 지어야 한다. 애플리케이션 이름부터 변수 이름까지 방대한 양의 이름을 작성해야 함은 틀림없다. 실제로 개발자 커뮤니티의 조사 결과에 따르면 이름짓기가 가장 어려운 테크닉으로 뽑힌 바도 있다.

자기 코드에 주석을 주렁주렁 달고 싶은 개발자는 없을 것이다. 따라서 명확하고 간결한 네이밍으로 주석을 달지 않아도 자신이 하려는 말을 잘 전달할 수 있는 네이밍이 필요하지만, 현실은 그렇지 못하다. 왜 그렇게 이름을 지었는지도 기억이 나지 않고 결국 코드를 다 뜯어봐야 기억이 나는 경우가 태반이다.

이름 짓기는 어렵긴 하지만 잘만 하면 코드를 짜기도 쉽고 이해하기도 쉽다. 다른 개발자와 소통하기도 쉬워지고, 공개할 경우 외부 개발자에게 인정도 받는다. 또한, 요즘과 같이 애자일처럼 문서를 최소화한다면 더욱더 필수인 기술이다.

이름 짓기는 창조가 아니라 조합

딱 말하자면 이름 짓기는 무에서 유를 창조하는 것이 조합적인 성격을 가진다. 실제로 깃허브의 인기 자바 소스를 분석한 결과 클래스, 함수, 변수 이름의 명명 특징을 연구한 결과 다음과 같은 중요한 네이밍 규칙을 데이터로 증명했다.

• 자바 네이밍 컨벤션을 철저히 준수한다.
  • 클래스는i UpperCamelCase
  • 함수와 변수는 LowerCamelCase
  • 상수는 UPPER_DELIMITER_CASE
• 네이밍은 보통 16글자, 3단어를 조합한다.
  • 클래스 네임: 3.18 단어
  • 함수 네임: 3.36 단어
  • 변수 네임: 2.57 단어
• 품사는 주로 명사, 동사, 형용사의 조합이다.
  • 명사 + 명사 + 명사
  • 동사 + 명사 + 명사
  • 형용사 + 명사 + 명사 등

코드의 네이밍 컨벤션은 영어 표기법을 성속받았다

네이밍 컨벤션은 기본적으로 영어 표기법을 준수한다.

• 중요하거나 크거나 특정한 것을 가리키거나 제목에 해당하는 명사는 모두 첫 글자를 대문자로 쓴다.
• 그런 명사들이 이어질 때는 첫 글자를 모두 대문자로 쓴다.
• 명사나 관사가 나닌 동사, 형용사 등은 소문자를 쓴다.

이 특성은 코딩에 그대로 적용된다. 그래서 파스칼, 카멜 표기법 등이 만들어졌다.

파스칼 표기법으로 클래스 이름 짓기

파스칼 표기법은 첫 글자를 대문자로 쓰는 방식이다. 주로 클래스 이름에 해당하며 그 이유는 클래스가 프로그래밍에서 가장 주요하고 높은 위치에 있고, 고유명사처럼 특정되기 때문이다. 인터페이스도 마찬가지

카멜 표기법으로 함수, 변수의 이름 짓기

카멜 표기법은 첫 단어를 빼고 나머지 단어의 첫 번째 글자만 대문자로 쓴다. 주로 함수나 변수에 사용한다. 함수는 동작을 시키는 명령어 개념이므로 첫 단어가 주로 동사다. 변수는 형용사로 시작하는 경우도 많다.

상수는 모두 대문자로 쓴다

영어 표기 원칙에서는 상수를 대문자로 쓰지 않는다. 하지만 프로그래밍에서는 값이 변해서는 안된다는 점을 강조하고 주의시키기 위해 가독성을 높이는 방법으로 대문자를 선택한 것이다. 요즘은 IDE가 발달하여 상수에 대한 경고나 다름을 잘 표시해주지만 통일성은 가지는 것이 좋다.

패키지와 모두 소문자로 쓴다

패키지와 모듈은 분명히 클래스나 함수보다 더 높은 위치다. 그러므로 패키지 이름과 모듈 이름은 당연히 대문자로 써야 할 것 같다. 하지만 실제로는 소문자로만 쓴다.

이것은 패키지와 모듈이 클래스를 모으거나 함수를 담아두는 통에 불과하기 때문이다. 클래스가 책이라고 하면 패키지는 전집이라고 볼 수 있다. 인식하고 구별하는 것은 각각의 책이지 전집이 아니다. 전집은 단지 책을 모아놓은 것에 불과하다.

BEM 표기법

CSS에서 사용하는 BEM표기법은 '대상__요소--상태'를 의미한다. 대상의 요소나 부분을 의미할 때는 언더스코어 두 개로 연결하고 대상이나 요소의 상태나 송석을 의미할 때는 하이픈 두 개로 연결한다.

가독성과 소통이 먼저다

대문자를 쓰든 소문자를 쓰든, 하이픈을 쓰든 안쓰든 가장 중요한 것은 소통 때문이다. 코드를 읽기 쉽게 만들고 다른 개발자와 소통하기 위해서다. 남들이 으레 그렇게 하니 따라 할 것이 아니라 그렇게 쓰는 이유를 알고 써야 한다.

이 이야기는 통일성이 왜 필요한지, 협업에서 같은 메타모델을 공유하는 것에 대한 중요성과 연관된다고 생각한다.

변수 이름을 잘 짓는 법

i는 변수 이름이지만 d는 아니다

가장 많이 쓰는 변수 이름은 i, Log, result였다. 사실 i는 정수를 뜻하는 integer와 지수를 뜻하는 index의 첫 글자로 간주되므로, 개발자가 반목문의 카운터나 배열의 인덱스로 많이 사용한다. 따라서 i, j, k의 흐름은 어색하지 않다.

마찬가지로 x, y를 통해 좌표를 나타내는 것도 이상하지 않지만 a나 b와 같은 아무런 의미가 없는 글자를 변수로 쓰는 것은 좋지 않다. 일자 day를 사용하고 싶다면 그냥 day를 쓰면 된다.

긴 이름? 짧은 이름? 검색 잘 되는 이름

소프트웨어 초창기 개발에서는 IDE도 뛰어나지 않고 용량도 제한적이라 굳이 변수 이름을 길게 지어서 오타를 낼 확률을 높이지 않았다. 하지만 요즘은 개발 환경이 매우 좋기 때문에 접두어를 붙이거나 약어를 사용할 필요가 없다. 따라서 명확하고 검색이 잘 되는 이름으로 네이밍을 해야 한다.

복수형을 나타내는 s를 붙일까 말까?

이 부분도 통일된 컨벤션을 따라가는 것이 좋지만, -s가 중간에 있을 땐 알아보기 힘들다. 따라서 중간에는 array나 list of를 쓰는 편이 좀 더 나을 수도 있다.

약어를 쓰는 것이 좋을까? 안 쓰는 것이 좋을까?

약어를 쓰는 것 또한 팀 내의 컨벤션을 따라가는 것이 좋지만, 어느정도 선을 지켜가며 사용하는 것이 좋다. 과도한 약어 사용은 코드를 더 어렵게 만들기 때문이다.

약어를 만드는 좋은 방법은 보편성을 기준으로 정하는 것이다. User Interface는 UI라고 표기하고, User Experience는 UX라고 쓴다.

중요한 단어를 앞에 쓴다

변수 이름을 여러 단어로 조합할 때는 순서를 잘 정해야 한다. 예를 들어 총 방문자 수를 나타내는 변수를 보통 totalvisitor로 그대로 번역해 변수로 사용하곤 한다. 하지만 이 변수를 사용할 때는 total로 검색하기보다 visitor로 검색하는 경우가 더 많을 것이다.

따라서 visitor를 앞에 쓸 것을 추천한다. 물론 요즘 개발 도구는 검색할 때 해당 단어가 포함된 클래스나 변수를 다 찾아주기 때문에 의미가 없을 수 있지만, 정렬된 결과를 위해 컨벤션을 지키는 것도 중요하다.

함수 이름 짓는 순서

함수 이름을 지을 때 처음에는 한글 문장에서 시작해서 몇 개의 영어 단어 조합으로 끝내는 경우가 많다. 이는 컨텍스트와 함수가 가지는 행위의 복잡성을 줄이는 작업을 통해 함수이름을 지어야 한다.

이 부분은 함수 자체가 얼마나 많은 일을 감당하고 있는지와 연괸된다.

좋은 이름의 기준, SMART

한 번에 좋은 이름을 지을 수는 없다

책의 공기인형의 사례와 같이 어떤 시점에서 바라보느냐에 따라 이름이 달라질 수 있다. 결국 앞에서 말한 내용과 같이 흔들리지 않는 보편성을 기준으로 이름을 지어야 한다. 그렇다고 스트레스까지 받을 필요없이 한 번에 완성할 수 없는 사실을 인정하자.

좋은 이름이 가진 5가지 특징

좋은 이름을 정하는 기준은 제각각이지만, 좋은 이름이 가지는 공통의 기준은 있다.

• easy to Search 검색하기 쉽고
• easy to Mix 조합하기 쉽고
• easy to Agree 수긍하기 쉽고
• easy to Remember 기억하기 쉽고
• easy to Type 입력하기 쉽고

easy to Search: 검색하기 쉽게 이름 짓는 법

검색하기 쉬운 이름은 고전적 범주화를 이용해 한 단계 상위 범주의 이름을 태그처럼 덧붙이면 된다. 고전적 범주화란 특정한 대상을 묶어 상위 범주를 만들어 이해하는 것이다. 예를 들어 소나무, 감나무, 배나무 같은 개별적인 대상을 나무라는 이름으로 범주화해서 이해한다. 그러면 어떤 나무를 보고 그 이름을 몰라도 일단 나무라고 인식하기 때문에 나무로 시작할 수 있다.

주의할 점은 같은 접두어를 가진 함수나 변수의 개수가 너무 많으면 안 붙이는 것만 못하다.

easy to Mix: 조합하기 쉽게 이름 짓는 법

가장 좋은 방법은 개발 언어의 문법과 조합하여 이름을 짓는 것이다. 개발 언어 자체가 이미 이름에 대한 기본 체계를 가지고 있기에 이를 잘 조합하여 이름을 짓자

easy to Agree: 수긍하기 쉽게 이름 짓는 법

수등할 수 있는 이름이란 누가 보더라도 그렇게 짓는 것이 더 낫다고 동의하는 이름이다. 이름 그 자체의 논리적 정합성이 있느냐 없느냐가 아니라 그 상황에서 그런 이름을 쓰는 것이 마땅하다고 생각할 수 있어야 하는 것이다.

easy to Remember: 기억하기 쉽게 이름 짓는 법

일상적이고 평법하고 무난한 점심은 뇌가 기억하지 않는다. 스스로 에너지를 효율적으로 사용하려는 뇌의 본능 때문이다. 반대로 얘기하면 비범하고 색다르고 인상적인 점심은 뇌가 스스로 기억해난다는 말이다. 뇌는 감각적인 것을 좋아한다.

시청각적으로 잘 지은 이름은 보통 연상어를 떠올려서 기억할 수 있도록 돕는다. (SSG의 쓱, SBS뉴스의 스브스 등)

easy to Type: 입력하기 쉽게 이름 짓는 법

자주 사용되거나 중요한 이름이라면 입력하기 쉬운지, 오타를 낼 가능성이 적은지, 다른 사람에게 말로 전달하기 쉬운지 검토해 보는 것이 좋다.

좋은 코드에는 주석이 없다?

이름을 잘 지으면 주석을 줄일 수 있다

이름을 잘 지으면 주석을 대폭 줄일 수 있다. 이름이 주석이 할 일을 대신하기 때문이다.

처음부터 주석 없이 코딩하는 연습을 하자

주석이 필요한 때도 많다

개발자마다 영어 실력에 차이가 있어서 누구에게 쉬운 단어라도 누구에게는 처음보는 단어일 수도 있다. 어순을 잘못 이해하면 엉뚱하게 생각하기도 한다. 따라서 주석이 필요해질 수 있는데, 이 경우를 제외하고 생각하더라도 개발과정에선 주석이 필요할 때가 많다.

주석은 결국 코드의 정확성을 높이고 버그를 줄이는 계기가 되기에 꼭 함수나 변수이름으로 설명하기 어렵다면 주석을 달자 (물론 설계의 복잡성이 문제가 될 수 있다.)

다른 개발자를 배려하는 주석 쓰기

코드는 의미를, 주석은 의도를

글은 의미를 전달하는 수단이다. 코드도 마찬가지다. 코드로 표현하지 못한 어떤 의도들은 주석으로 쓸 수밖에 없는데, 개발자가 어떤 의도를 전달하는 이유는 다른 개발자를 위한 것이다. 다른 개발자란, 미래의 본인도 포함한다.

주석의 반복

주석도 코드와 마찬가지로 반복적인 성격을 가지면 주석으로의 역할이 줄어들 수 있다. 위에서 부터 아래로 코드를 읽어나갈 때 같은 주석이 반복된다면 궁금증이 들 수 있다. 하지만 예제를 검색해보면서 이해하는 사람이 있다고 한다면 반복되는 주석은 반드시 지워야만 하는 것은 아니다.

주석의 발췌와 요약

발췌는 중요한 것을 뽑아내는 것이다. 중요한 것을 뽑으려면 덜 중요한 것을 빼야 한다. 한 문단에 같은 내용에 모두 주석을 달아 내용을 설명하기 보다 코드와 주석을 묶어 같은 내용을 한 묶음으로 설명하는 방식이 좋다. 또한 코드에 며시된 조건들은 주석에 넣기 보다 의도를 설명하는 주석을 달아야 한다.

주석도 코드다

주석의 유명한 말은 지속적인 유지보수가 되지 않는 주석은 쓰지 말라는 것이다. 주석은 코드와 마찬가지로 지속적으로 업데이트가 되어야 하는데, 의도나 이유를 설명하는 주석이 코드의 변경을 따라가지 못하면 다른 개발자는 너무 쉽게 오해한다. 코드는 디버깅이 가능하지만 주석은 그렇지 않다.

이러한 악순환에서 벗어나기 위한 가장 좋은 방법은 주석도 코드라고 생각하는 것이다. 코드 리뷰를 하며 주석도 같이 리뷰를 하고 불필요한 주석은 없애고 꼭 필요한 주석은 반드시 코드처럼 다뤄야 한다.

느낀점

다른 책에서 다루는 코드 작성법을 넘어 핵심적인 내용들을 잘 요약해둔 것 같다. 이런 내용을 읽고 실제 코드를 쓸 때 어느정도 반영이 되어서 들어가는 부분도 재밌다고 생각이 되지만, 결국 가장 좋은 것은 남의 코드를 많이 보고 내가 코드를 많이 작성해보는 것이라고 생각된다.