MaintainableCode/Naming

UserPreferences

1. 한 글자로 이루어진 변수 이름을 사용하지 말자.
2. 오타를 주의하자.
3. 추상적인 이름을 사용하지 말자.
4. 약어(acronym)를 사용하지 말자.
5. 너무 많은 동의어를 사용하지 말자.
6. 다른 언어를 identifier로 사용하지 말자. (영어만 사용하자.)
7. 대문자를 단어 중간에서 사용하지 말자.
8. 이름을 재사용하지 말자.
9. 밑줄(underscore)를 변수 이름으로 사용하지 말자.
10. 주석 등을 여러 가지 언어로 작성하지 말자.
11. 변수 이름에다 자신만이 아는 의미를 부여하지 말자.
12. 코딩 컨벤션을 무시하지 말자.
13. 비슷하게 보일 수 있는 글자들을 조심하자.
14. 전역 변수와 같은 이름의 변수를 선언하지 말자.
15. 스코프를 과용하지 말자.
16. 전혀 다른 목적으로 임시 변수를 재사용하지 말자.
17. 같은 맥락의 변수라면 똑같은 이름을 사용하자.
18. 함수 이름을 제대로 짓자.
19. 헝가리언 표기법을 사용할 때는 조심하자.
20. 헝가리언 표기법을 사용한다면, 변수의 타입과 이름을 항상 일치시키자.
21. 로컬 구조체나 클래스 이름을 재사용하지 말자.

1 한 글자로 이루어진 변수 이름을 사용하지 말자.

무슨 말인지 코딩 좀 해본 사람은 알 것이다. 하지만 여기에 대해서는 반론이 있을 소지가 있다. 예를 들어 for 루프 안에 인덱스 값이나, 좌표계의 x, y, z 같은 경우에는 짧은 쪽을 사용하는 것이 낫다. XCoord, YCoord, ZCoord... 타이핑도 타이핑이지만, 코드를 읽을 때도 짜증나지 않는가? 즉 짧아도 의미가 충분히 전달된다고 판단될 때는, 짧은 쪽을 선호하라는 말이다. 개인적인 기준은, 함수 인자 이름은 길게, 로컬 변수 이름은 짧게... 정도이다.

2 오타를 주의하자.

SetPintleOpening과 SetPintalClosing 같은 경우가 되겠다. 연관이 있는 함수인데도 불구하고, 스펠링이 틀리면, 검색할 때 매우 불편하다. 이런 경우는 거의 없겠지만...

3 추상적인 이름을 사용하지 말자.

it, everything, data, handle, stuff, do, routine, perform 같은 것이나, routineX48, PerformDataFunction, DoIt, HandleStuff, do_args_method 같은 이름은 작성자 이외에는 아무도 그 뜻을 금방 짐작할 수가 없다. 이런 종류의 이름이 많으면, 코드를 라인 단위로 모두 살펴봐야 하므로 상당히 괴로워진다.

4 약어(acronym)를 사용하지 말자.

될 수 있는 한, 약어를 사용하지 마라. Trigger Node의 준말, Tode... 아무 주석 없이 Tode란 단어를 봤을 때, Trigger Node를 바로 연상할 사람이 있을까?

5 너무 많은 동의어를 사용하지 말자.

한 클래스 안에 display(), show(), present()란 세 함수가 있다면, 각각이 어떤 역할을 할 지 추측할 수 있는가? 비슷한 맥락으로, 거의 다른 일을 하는 함수에다 비슷한 이름을 붙이지 마라. 예를 들어 파일에다 출력하는 함수, 프린터에다 출력하는 함수, 화면에다 출력하는 함수에다 모두 print()라는 이름을 사용하는 경우다.

6 다른 언어를 identifier로 사용하지 말자. (영어만 사용하자.)

한국어를 영어로 표현한 변수, jongsung, jungsung. 이런 식의 이름 짓기는 다른 사람이 알아보기 힘들다. 특히나 외국인이 보게 되는 경우라면 문제는 더욱 커진다. 귀찮더라도 final consonant와 같은 식으로 번역을 해서 코딩하라.

7 대문자를 단어 중간에서 사용하지 말자.

CapiTaliSaTion... 금방 알아봤다면 당신은 외계인이다.

8 이름을 재사용하지 말자.

C/C++ 코드 같은 경우, 안쪽의 블록에서 바깥쪽에 있는 블록과 똑같은 이름을 가진 변수를 사용할 수 있다. 로컬 네임을 우선시한다는 규칙이 있기 때문에, 컴파일되며 돌아가기는 하겠지만, 이런 류의 코드는 진짜 고치기 두렵다. 변수 하나를 고칠 때마다 스코프를 확인해야 한다!

9 밑줄(underscore)를 변수 이름으로 사용하지 말자.

C/C++에서는 _나 __도 변수 이름으로 사용할 수 있기는 하다. 일하기 싫은가?

10 주석 등을 여러 가지 언어로 작성하지 말자.

우리 나라에는 거의 해당 사항이 없다고 할 수 있다. 유럽 같은 경우에는 한 나라 안에서도 여러 언어를 사용하는 경우가 많으니깐...

11 변수 이름에다 자신만이 아는 의미를 부여하지 말자.

marypoppins = (superman + starship) / god; 

자, 이 코드는 도대체 무엇을 하는 것인가?

12 코딩 컨벤션을 무시하지 말자.

이런 건 이런 식으로, 저런 건 저런 식으로 한다고 규칙을 정했다면, 반드시 규칙을 지켜라.

13 비슷하게 보일 수 있는 글자들을 조심하자.

어떤 폰트로 코드를 보느냐에 따라 다르겠지만, 소문자 L같은 경우는 숫자 1과 비슷해서 문제를 일으키는 경우가 있다. 게다가 L은 long constant를 나타내기 위해 숫자 뒤에 붙을 때가 있다. 즉 10l을 101로 보는 경우가 있다는 말이다. 이런 경우는 반드시 대문자를 사용하라. 이외에도 uvw wW gq9 2z 5s il17|!j oO08 경우의 수는 많다.

14 전역 변수와 같은 이름의 변수를 선언하지 말자.

A란 모듈 안에다 전역 변수를 선언하고, B란 모듈 안에서 같은 이름의 로컬 변수를 선언한 다음, A를 포함하면 자칫 A의 전역 변수를 사용하고 있다는 착각을 줄 수 있다. 이런 경우에는 "g_", "m_" 같은 접두어를 사용하라.

15 스코프를 과용하지 말자.

identifier 이름을 재사용하지 말라는 규칙과 같은 맥락이다.

16 전혀 다른 목적으로 임시 변수를 재사용하지 말자.

함수의 위쪽에서 사용한 임시 변수에다 다른 의미를 부여해서 재사용하지 마라. 다른 의미를 부여하는 부분에 주석마저 달려있지 않다면, 이해하기 힘든 코드가 된다.

17 같은 맥락의 변수라면 똑같은 이름을 사용하자.

예를 들어 색깔을 나타내는 변수가 있다면, color 하나만을 사용하라. color, colour, kulerz... 같은 뜻의 다른 단어는 물론이거니와, 줄임말 같은 것도 혼용하지 마라. 다른 이름을 혼용하면, 텍스트 에디터에서 찾기 기능으로 코드의 흐름을 이해하고자 할 때 방해가 된다.

18 함수 이름을 제대로 짓자.

isValid(x)라는 함수 호출은 대략 보기에 bool isValid(const type& arg) const 정도로 보일 것이다. 이 함수가 만일 인자의 non-const 레퍼런스를 받아, 내부값을 수정하는 함수라면, 이름을 잘못 지어도 한참 잘못 지은 것이다.

19 헝가리언 표기법을 사용할 때는 조심하자.

기본적인 표기법이 아니라 자신만의 규칙을 만들어내어 사용하는 이들이 있다. a_crszkvc30LastNameCol라는 변수가... const이고, 참조이고, 함수 인자에다가, varchar(30) 형식의 데이터베이스의 컬럼 값을 나타내며, 테이블의 주키라는 것을 알기까지는 적어도 며칠은 걸릴 것이다. 절대 이런 방식으로 코딩하지 말라.

예전에 이런 식으로 코딩하는 분을 본 적이 있는데... 변수 이름이 화면의 4분의1 정도를 차지하는 듯 했다. 나중에 인수인계받은 분한테 물어보니, 익숙해지면 나름대로 괜찮다던데... 그러나 절대 좋지 않다.

개인적으로 헝가리언 표기법은 포인터 정도를 제외하고는 사용하지 않는 것이 좋다고 본다. 코드를 줄줄 읽어나갈 때, m_lpszName, nAge 이런 식의 변수들은 괜히 머리 속에서 해석을 한번 더 하게 만들기 때문이다. 사람의 머리는 한 번에 7가지의 생각 밖에 할 수 없다고 한다. 왜 7이라는 숫자가 나왔는지는 모르겠다만, 중요한 점은 동시에 할 수 있는 생각의 수가 제한되어 있다는 것이다.

20 헝가리언 표기법을 사용한다면, 변수의 타입과 이름을 항상 일치시키자.

원래 코드는 WndProc(HWND hW, WORD wMsg, WORD wParam, LONG lParam)와 같은 형식이었는데, 인수들의 타입을 (HWND hW, UINT wMsg, WPARAM wParam, LPARAM lParam)과 같이 바꾸면서, 변수 이름을 그대로 두는 것은 잘못된 주석을 그대로 두는 것과 같은 행위다.

21 로컬 구조체나 클래스 이름을 재사용하지 말자.

코드를 이해하기 위해서, 디버거로 프로그램을 한단계씩 수행하며 이런저런 값을 확인할 때가 있다. 로컬 구조체나 클래스 이름을 재사용하는 경우, 디버거에서 변수를 expand해서 값을 확인할 때 엉뚱한 구조체로 인식하는 경우가 있다.

• see also MaintainableCode
  

• CategoryDesign