사용자 도구

사이트 도구


kb:maintainablecodenaming

차이

문서의 선택한 두 판 사이의 차이를 보여줍니다.

차이 보기로 링크

kb:maintainablecodenaming [2014/11/08 16:51] (현재)
줄 1: 줄 1:
 +====== Maintainable Code / Naming ======
 +변수, 함수, 클래스 이름 등에 관련된 사항
 +
 +====== 목록 ======
 +==== - 한 글자로 이루어진 변수 이름을 사용하지 말자. ====
 +무슨 말인지 코딩 좀 해본 사람은 알 것이다. 하지만 여기에 대해서는 반론이 있을 소지가 있다. 예를 들어 for 루프 안에 인덱스 값이나, 좌표계의 x, y, z 같은 경우에는 짧은 쪽을 사용하는 것이 낫다. XCoord, YCoord, ZCoord... 타이핑도 타이핑이지만,​ 코드를 읽을 때도 짜증나지 않는가? 즉 짧아도 의미가 충분히 전달된다고 판단될 때는, 짧은 쪽을 선호하라는 말이다. 개인적인 기준은, 함수 인자 이름은 길게, 로컬 변수 이름은 짧게... 정도이다.
 +
 +==== - 오타를 주의하자. ====
 +SetPintleOpening과 SetPintalClosing 같은 경우가 되겠다. 연관이 있는 함수인데도 불구하고,​ 스펠링이 틀리면, 검색할 때 매우 불편하다. 이런 경우는 거의 없겠지만...
 +  ​
 +==== - 추상적인 이름을 사용하지 말자. ====
 +it, everything, data, handle, stuff, do, routine, perform 같은 것이나, routineX48, PerformDataFunction,​ DoIt, HandleStuff,​ do_args_method 같은 이름은 작성자 이외에는 아무도 그 뜻을 금방 짐작할 수가 없다. 이런 종류의 이름이 많으면, 코드를 라인 단위로 모두 살펴봐야 하므로 상당히 괴로워진다.
 + 
 +==== - 약어(acronym)를 사용하지 말자. ====
 +될 수 있는 한, 약어를 사용하지 마라. Trigger Node의 준말, Tode... 아무 주석 없이 Tode란 단어를 봤을 때, Trigger Node를 바로 연상할 사람이 있을까?
 + 
 +==== - 너무 많은 동의어를 사용하지 말자. ====
 +한 클래스 안에 display(), show(), present()란 세 함수가 있다면, 각각이 어떤 역할을 할 지 추측할 수 있는가? 비슷한 맥락으로,​ 거의 다른 일을 하는 함수에다 비슷한 이름을 붙이지 마라. 예를 들어 파일에다 출력하는 함수, 프린터에다 출력하는 함수, 화면에다 출력하는 함수에다 모두 print()라는 이름을 사용하는 경우다.
 + 
 +==== - 다른 언어를 identifier로 사용하지 말자. (영어만 사용하자.) ====
 +한국어를 영어로 표현한 변수, jongsung, jungsung. 이런 식의 이름 짓기는 다른 사람이 알아보기 힘들다. 특히나 외국인이 보게 되는 경우라면 문제는 더욱 커진다. 귀찮더라도 final consonant와 같은 식으로 번역을 해서 코딩하라.
 + 
 +==== - 대문자를 단어 중간에서 사용하지 말자. ====
 +CapiTaliSaTion... 금방 알아봤다면 당신은 외계인이다.
 + 
 +==== - 이름을 재사용하지 말자. ====
 +C/C++ 코드 같은 경우, 안쪽의 블록에서 바깥쪽에 있는 블록과 똑같은 이름을 가진 변수를 사용할 수 있다. 로컬 네임을 우선시한다는 규칙이 있기 때문에, 컴파일되며 돌아가기는 하겠지만,​ 이런 류의 코드는 진짜 고치기 두렵다. 변수 하나를 고칠 때마다 스코프를 확인해야 한다!
 + 
 +==== - 밑줄(underscore)를 변수 이름으로 사용하지 말자. ====
 +C/​C++에서는 _나 __도 변수 이름으로 사용할 수 있기는 하다. 일하기 싫은가?
 + 
 +==== - 주석 등을 여러 가지 언어로 작성하지 말자. ====
 +우리 나라에는 거의 해당 사항이 없다고 할 수 있다. 유럽 같은 경우에는 한 나라 안에서도 여러 언어를 사용하는 경우가 많으니깐...
 +
 +==== - 변수 이름에다 자신만이 아는 의미를 부여하지 말자. ====
 +<​code>​
 +marypoppins = (superman + starship) / god;
 +</​code>​
 +
 +자, 이 코드는 도대체 무엇을 하는 것인가? ​
 +
 +==== - 코딩 컨벤션을 무시하지 말자. ====
 +이런 건 이런 식으로, 저런 건 저런 식으로 한다고 규칙을 정했다면,​ 반드시 규칙을 지켜라.
 +
 +==== - 비슷하게 보일 수 있는 글자들을 조심하자. ====
 +어떤 폰트로 코드를 보느냐에 따라 다르겠지만,​ 소문자 L같은 경우는 숫자 1과 비슷해서 문제를 일으키는 경우가 있다. 게다가 L은 long constant를 나타내기 위해 숫자 뒤에 붙을 때가 있다. 즉 10l을 101로 보는 경우가 있다는 말이다. 이런 경우는 반드시 대문자를 사용하라. 이외에도 uvw wW gq9 2z 5s il17|!j oO08 경우의 수는 많다.
 +
 +==== - 전역 변수와 같은 이름의 변수를 선언하지 말자. ====
 +A란 모듈 안에다 전역 변수를 선언하고,​ B란 모듈 안에서 같은 이름의 로컬 변수를 선언한 다음, A를 포함하면 자칫 A의 전역 변수를 사용하고 있다는 착각을 줄 수 있다. 이런 경우에는 "​g_",​ "​m_"​ 같은 접두어를 사용하라.
 +
 +==== - 스코프를 과용하지 말자. ====
 +identifier 이름을 재사용하지 말라는 규칙과 같은 맥락이다.
 +
 +==== - 전혀 다른 목적으로 임시 변수를 재사용하지 말자. ====
 +함수의 위쪽에서 사용한 임시 변수에다 다른 의미를 부여해서 재사용하지 마라. 다른 의미를 부여하는 부분에 주석마저 달려있지 않다면, 이해하기 힘든 코드가 된다.
 +
 +==== - 같은 맥락의 변수라면 똑같은 이름을 사용하자. ====
 +예를 들어 색깔을 나타내는 변수가 있다면, color 하나만을 사용하라. color, colour, kulerz... 같은 뜻의 다른 단어는 물론이거니와,​ 줄임말 같은 것도 혼용하지 마라. 다른 이름을 혼용하면,​ 텍스트 에디터에서 찾기 기능으로 코드의 흐름을 이해하고자 할 때 방해가 된다. ​
 +
 +==== - 함수 이름을 제대로 짓자. ====
 +isValid(x)라는 함수 호출은 대략 보기에 bool isValid(const type& arg) const 정도로 보일 것이다. 이 함수가 만일 인자의 non-const 레퍼런스를 받아, 내부값을 수정하는 함수라면,​ 이름을 잘못 지어도 한참 잘못 지은 것이다.
 +
 +==== - 헝가리언 표기법을 사용할 때는 조심하자. ====
 +기본적인 표기법이 아니라 자신만의 규칙을 만들어내어 사용하는 이들이 있다. a_crszkvc30LastNameCol라는 변수가... const이고,​ 참조이고,​ 함수 인자에다가,​ varchar(30) 형식의 데이터베이스의 컬럼 값을 나타내며,​ 테이블의 주키라는 것을 알기까지는 적어도 며칠은 걸릴 것이다. 절대 이런 방식으로 코딩하지 말라.
 +
 +:!: 예전에 이런 식으로 코딩하는 분을 본 적이 있는데... 변수 이름이 화면의 4분의1 정도를 차지하는 듯 했다. 나중에 인수인계받은 분한테 물어보니,​ 익숙해지면 나름대로 괜찮다던데... 그러나 절대 좋지 않다.
 +
 +:!: 개인적으로 헝가리언 표기법은 포인터 정도를 제외하고는 사용하지 않는 것이 좋다고 본다. 코드를 줄줄 읽어나갈 때, m_lpszName, nAge 이런 식의 변수들은 괜히 머리 속에서 해석을 한번 더 하게 만들기 때문이다. 사람의 머리는 한 번에 7가지의 생각 밖에 할 수 없다고 한다. 왜 7이라는 숫자가 나왔는지는 모르겠다만,​ 중요한 점은 동시에 할 수 있는 생각의 수가 제한되어 있다는 것이다.
 +
 +
 +==== - 헝가리언 표기법을 사용한다면,​ 변수의 타입과 이름을 항상 일치시키자. ====
 +원래 코드는 WndProc(HWND hW, WORD wMsg, WORD wParam, LONG lParam)와 같은 형식이었는데,​ 인수들의 타입을 (HWND hW, UINT wMsg, WPARAM wParam, LPARAM lParam)과 같이 바꾸면서,​ 변수 이름을 그대로 두는 것은 잘못된 주석을 그대로 두는 것과 같은 행위다.
 +
 +==== - 로컬 구조체나 클래스 이름을 재사용하지 말자. ====
 +코드를 이해하기 위해서, 디버거로 프로그램을 한단계씩 수행하며 이런저런 값을 확인할 때가 있다. 로컬 구조체나 클래스 이름을 재사용하는 경우, 디버거에서 변수를 expand해서 값을 확인할 때 엉뚱한 구조체로 인식하는 경우가 있다.
 +
 +----
 +  * see also [[MaintainableCode]]
  
kb/maintainablecodenaming.txt · 마지막으로 수정됨: 2014/11/08 16:51 (바깥 편집)