개발자의 글쓰기
- "개발자의 글쓰기"/김철수/위키북스를 읽고 요약한 독후감입니다.
책의 내용 요약
- 함수, 변수의 이름을 자기가 지어놓고도 나중에 그 뜻을 모를 때도 많다.
- 요즘같이 애자일이 주목받아서 문서를 최소로 만드는 시대에 문서 대신에 코드로 소통하려면 좋은 이름 짓기는 필수다.
- 이름짓기는 창조과정이 아니라 정해진 원칙으로 적절한 단어를 선택해 조합하는 과정일 뿐이다.
코드의 네이밍 컨벤션은 영어 표기법을 상속받았다.
- 기본적으로 영어의 표기법을 준수한다.
- 영어에서 대문자로 쓰는 것
- 중요한 것
- 큰것
- 특정한 것을 가리키는 것
- 제목
- 예시
- 고유명사는 위치에 관계없이 대문자로 시작한다.
- I went to Tokyo.
- 이름 앞에 오는 직함은 대문자로 쓴다.
- Doctor Mr.Micheal
- 제목에 나오는 첫 단어의 첫글자, 마지막 단어의 첫글자, 관사의 첫글자는 대문자로 쓴다.
- Marvel's The Avengers
- 고유명사는 위치에 관계없이 대문자로 시작한다.
- 영어에서 대문자로 쓰는 것
- 네이밍 컨벤션
- 클래스(파스칼 표기법)
- 주로 클래스 이름에 사용
- 클래스가 프로그래밍에서 가장 주요하고 높은 위치에 있고, 고유명사처럼 특정되며, 명사로 돼 있기 때문
- 클래스 이름의 첫 글자는 어디에 위치하든 모두 첫 글자를 대문자로 쓴다.
- 변수, 함수(카멜 표기법)
- 주로 함수나 변수에 사용
- 영어의 기본은 명사가 관사가 아닌경우 첫 글자를 소문자로 시작한다.(형용사, 동사 등)
- 따라서 형용사난 동사로 시작하는 함수, 변수는 첫 글자를 소문자로 쓴다.
- 상수(모두 대문자)
- 상수는 영어표기법과 관계없이 변수와 구별하기 위해 모든 글자를 대문자로 쓰고, 언더스코어로 연결한다.
- 패키지, 모듈(모두 소문자)
- 클래스나 함수보다 더 높은 위치이지만 소문자로 쓴다.
- 패키지나 모듈이 클래스를 모으거나 함수를 담아놓은 통에 불과하기 때문
- 패키지 자체의 중요도가 낮다고 본것.
- 대문자로 쓸 경우 클래스 이름과 혼동할 수 있기 때문에 클래스와 구별하려는 실용적 목적도 있다.
- CSS(BEM표기법)
.form {} .form__button {} .form__button--disabled {}- 언더스코어
_두개(__)- 대상의 요소나 부분을 의미
__button
- 하이픈
-두개(—)- 대상이나 요소의 상태나 속성을 의미
--disabled
- 언더스코어
- 클래스(파스칼 표기법)
좋은 이름의 기준
- 과거의 습관
- 변수 이름이 길면 오탈자가 많이 난다?
- 예전에는 긴 이름이 오탈자로 이어질 확률이 높았지만 요즘은 통합개발환경의 발전, 자동완성 등으로 그럴 확률이 줄었다.
- 길이보다는 검색이 잘 되고 주석없이 이해할 수 있는 것이 중요하다.
- 나쁜예
getUserName() // 사용자가 입력한 텍스트 인풋 필드에서 가져옴 getUserName() // DB에서 아이디와 일치하는 이름을 가져옴 getUserName() // 세션에서 아이디와 일치하는 이름을 가져옴 - 좋은예
getUserNameFromInputFiled() getUserNameFromDB() getUserNameFromSession()
- 나쁜예
- 헝가리안 표기법
- 유래
- 변수 이름에 type을 포함하는 것
- n
- is
- button → btn
- image → img
- 지금은 개발환경의 발전으로 이 역시 사용할 필요가 없어졌다. 오히려 사용하지 말것을 권장한다.
- 변수 이름이 길면 오탈자가 많이 난다?
- 복수형
-s보다는list of,array등 복수의 의미하는 단어를 붙여 작성하는 편이 헷갈리지 않는다.
- 약어
- 보편성을 기준으로 쓴다.
- temp, param, arg 등 이미 익숙한 것은 괜찮다.
- 보편성을 기준으로 쓴다.
- 순서
- 중요한 단어를 앞에 쓴다.
- 예시
TotalVisitor보다는VisitorTotal
- 함수 이름 짓기 tip
- 1함수, 1업무 규칙 지키기
- 순서
- 핵심 기능을 영어로 서술
- 다듬기
- 정관사, 소유격 빼기
- user's name → user name
- of는 앞뒤 단어를 바꾸는 것으로 대체
- list of user → user list
- 정관사, 소유격 빼기
- 띄어쓰기 없애고 첫 글자 대문자로 바꾸기
- 의미상 필요없는 단어 삭제
- 좋은 이름이 가진 다섯가지 특징
- SMART
- easy to Search: 검색하기 쉬운 이름
- 상위 범주를 이름에 포함하기
ERROR_SERVER_TIMEOUT ERROR_NO_RESULT - 만약에 이런 ERROR가 수백개라면, 그 안에서 한 번 더 범주화할 필요가 있음
SERVER_ERROR_TIMEOUT SERVER_ERROR_NO_RESULT SERVER_ERROR_BAD_REQUEST INTERFACE_ERROR...
- 상위 범주를 이름에 포함하기
- easy to Mix
- easy to Agree
- 보편적으로 동의하는 규칙을 따르는 것이 좋음
- 예: "이름의 정밀도는 영역의 범위에 따라 달라진다."
- 보편적으로 동의하는 규칙을 따르는 것이 좋음
- easy to Remember
- 시각, 청각적으로 완결된 단어가 기억하기 쉬움
- 창의력을 발휘하기 보다 보편적으로 쓰이는 단어를 사용하기
- easy to Type
- 오탈자가 많이 나는 단어사용 자제
- 연속된 철자
- success
- 묵음
- lambda
- je/ei
- chief
- sion/tion
- position
- uous/ous/us
- fabulous
- 연속된 철자
- 오탈자가 많이 나는 단어사용 자제
주석
- 코드를 잘 짜면 주석이 필요없다. 하지만 주석이 필요한 때도 있음
- 보편적으로 잘 헷갈리는 영어 표현의 경우
- 3글자 이하
- 3 and under
- 3 or less
- 3 or below
- 3글자 미만
- under 3
- below 3
- less than 3
- 3글자 이하
- 보편적으로 잘 헷갈리는 영어 표현의 경우
- 주석이 제 역할에만 충실하다면 양은 중요하지 않음
- 코드는 의미를, 주석은 의도를
- 코드자체에 개발자의 의도를 전달할 수 없음
- 따라서 왜 이렇게 작성했는지, 더 좋은 방법을 제시해주는 등의 내용은 주석 이용
- 코드를 이렇게 짠 이유를 알려주는 것(속도, 에러방지)
- 할 일, 주의, 개선 아이디어
- TODO-할 일
- XXX-주의
- HACK-개선 아이디어
- 코드가 반복되는 경우 주석도 반복됨
- 개발 문서 같은 경우 독자가 필요한 부분만 검색해서 읽기 때문에, 주석도 같이 반복되어야 함
- 무조건 처음 한 번만 쓰고, 내용이 반복되는 주석을 지워야만 좋은 것은 아님
- 주석은 코드와 달리 신경을 덜 쓰기 때문에 한 번 잘못 작성되면 바로잡기 쉽지 않음
- 잘못된 주석이 늘어나면 주석을 믿지 않는 풍토가 생기고, 더 주석에 신경쓰지 않게 됨 → 악순환의 늪!
- 주석도 코드라고 생각하면서 코드 리뷰할때 주석 리뷰까지 꼼꼼히 해야함
- 불필요한 주석은 삭제, 필요한 주석은 코드처럼!
느낀점
- '좋은 이름'은 추상적인 것이 아니다.
- 보편적으로 지키는 규칙과 기준이 있고 그것들을 잘 기억하고 지키면 이름을 잘 지을 수 있다.
- 코드를 바꿔서 주석을 줄일 수 있다면 주석을 다는 대신 코드를 수정하자!
- 꼭 필요한 주석은 코드처럼 다루자!
노트정리