개발자의 글쓰기 - (2장. 개발 시간을 줄여주는 이름 짓기와 주석 쓰기)

http://www.yes24.com/Product/Goods/79378905

개발자의 글쓰기 - YES24

 

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

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

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

• 이름을 잘못 지어서 코드를 이해하기 어렵고, 자기가 이름을 지어놓고도 나중에는 그 이름이 무엇을 뜻하는지 모를 때도 많다.
• 잘만 하면 코드를 짜기도 쉽고 이해하기도 쉽다.
• 또한 다른 개발자 및 외부와 소통도 쉽고 문서를 대신할 수도 있다.

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

• 이름 짓기는 무에서 유를 창조하는 것이 아니라 기존 방식이나 이름을 차용해서 새로운 이름을 짓는 경우가 대부분이다.
• 오픈소스의 네이밍 특징들은 몇 가지 중요한 네이밍 규칙을 데이터로 증명했다.
  • 자바 네이밍 컨벤션을 철저히 준수한다.
    • 클래스는 UpperCamelCase
    • 함수와 변수는 lowerCamelCase
    • 상수는 UPPER_DELMITER_CASE
  • 네이밍은 보통 16글자, 3 단어를 조합한다.
    • 클래스 네임 : 3.18 단어
    • 함수 네임 : 3.36 단어
    • 변수 네임 : 2.57 단어
  • 품사는 주로 명사, 동사, 형용사의 조합이다.
    • 명사 + 명사 + 명사
    • 동사 + 명사 + 명사
    • 형용사 + 명사 + 명사 등

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

• 파스칼 표기법과 카멜 표기법은 영어의 대문자 표기 원칙을 상속받은 것이다.
  1. 중요하거나 크거나 특정한 것을 가리키거나 제목에 해당하는 명사는 모두 첫 글자를 대문자로 쓴다.
  2. 그런 명사들이 이어질 때는 첫 글자를 모두 대문자로 쓴다.
  3. 명사나 관사가 아닌 동사, 형용사 등은 소문자를 쓴다.

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

• 파스칼 표기법은 모든 단어에서 첫 글자를 대문자로 쓰는 방식이다.
• 클래스가 프로그래밍에서 가장 주요하고 높은 위치에 있고, 고유명사처럼 특징되며, 명사로 돼 있기 때문이다.

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

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

상수는 모두 대문자로 쓴다.

• 프로그래밍할 때는 소문자를 쓰는 변수와 구별하기 위해 상수를 모두 대문자로 쓰고 언더스코어(_)로 단어를 연결한다.
• 상수는 값이 변해서는 안된다는 점을 강조하고 주의시키기 위해 가독성을 높이는 방법으로 대문자를 선택한 것이다.

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

• 패키지 이름과 모듈 이름은 당연히 대문자로 써야 할 것 같지만 클래스를 모으거나 함수를 담아놓은 통에 불과하다.
• 또한 패키지 이름과 클래스 이름을 혼동할 수 있고, 모듈 이름과 함수 이름을 헷갈릴 수 있기 때문이다.

BEM 표기법

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

.form {
}
.form_button {
}
.form_button--disabled {
}

가독성과 소통이 먼저다.

• 중요한 것은 표기법 자체가 아니라 그렇게 쓰는 이유다.
• 코드를 읽기 쉽게 만들고 다른 개발자와 소통하기 위해서다.
• 가독성이 높다고 소통이 더 잘되는 것은 아니다. 소통이 잘 되려면 서로가 같은 컨벤션을 지켜야 한다.

02 변수 이름을 잘 짓는 법

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

• x나 y , i 같은 의미가 있는 변수 이름으로 사용해도 이상할 것이 전혀 없다.
• 하지만 a나 b와 같이 아무런 의미가 없는 글자를 변수는 쓰는 것은 좋지 않다.
• 또한 그냥 일자를 뜻하는 day를 사용할 때도 그냥 day를 사용하기보다는 의미를 담은 day, 예를 들어 finalDay, currentDay 등을 사용하는 게 더 좋다.

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

• 소프트웨어 초창기에는 IDE의 도움을 받기가 힘들었고, 그렇기 때문에 오탈자에 대한 위험을 피하기 위해 많은 축약어를 사용했다.
• 요즘은 개발 환경이 좋아져서 자동완성이나 변수 명을 제안해 준다.
• 헝가리안 표기법은 IDE가 발전하기 전에는 유익했지만 이제는 거의 레거시가 됐다고 봐도 무방하다.

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

• 배열을 복수로 나타내는 방법은 변수명을 복수형으로 사용하는 것이다.
• 다만 여러 단어를 섞어 쓰다 보면 복수형 -s가 눈에 잘 띄지 않는다.
• 그래서 array나 listOf를 쓰기도 한다.
• 프로젝트 안에서 규칙을 하나로 통일해야 한다.

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

• 약어를 만드는 좋은 방법은 보편성을 기준으로 정하는 것이다.
• document -> doc, UserInterface -> UI 등등

중요한 단어를 앞에 쓴다.

• 예를 들어 '총 방문자 수'를 나타내는 변수의 경우 totalVistor 보다 방문자가 더 중요한 의미여서 vistorTotal로 쓸 것을 추천한다 -> 사실 이 부분은 납득이 잘 안 간다.

함수 이름 짓는 순서

• 요구사항 중 사용자가 할 일을 모두 제거하고 시스템이 할 일들로 문장을 간결하게 만든다.
• 몇 개의 함수가 도출되는지 결정한다.
• 영어로 변경하면서 정관사 및 불필요한 단어들을 제거한다.
• 띄워쓰기를 제거하고, 대문자로 변경한다

03. 좋은 이름의 기준, SMART

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

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

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

• 검색이 어렵다면 우리는 이름을 찾는데 시간을 소비하거나 동일한 기능 함수를 새롭게 만들 수 있다.
• 고전적인 범주화를 이용해 한 단계 상위 범주의 이름을 태그처럼 덧붙이면 된다.
• 다양한 에러 이름 상수들 -> 접두사 'ERROR_' 를 붙여 검색하기 쉽게 작성
• 다만 접두사를 붙인 대상이 너무 많이 생길 경우 주의해서 사용하자

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

• 속성으로 이름을 짓는다면 속성이 변경되면 이름이 전부 변경되어야 한다.
• 속성 대신에 개념을 가지고 지을 수 있다.
• 다만 동일한 개념에 비슷한 것들이 있을 수 있다. 그렇기 때문에 개발 언어의 문법과 조합해 이름을 짓는 것이다.
• 예(css) : .blue_text (X, 속성을 가지고 이름 짓기) , .title (X, 개념만 가지고 이름 짓기), .h1.title ( O, 언어의 문법과 개념을 조합해 네이밍 )

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

• 특정 상황에서 특정 이름을 쓰는 것이 마땅하다고 생각할 수 있어야 한다.
• 직관적인 루프문 안에서는 i,j,k를 사용하는 것이 틀린 건 아니다.
• 또한 대상을 꼭 구별할 필요가 없거나, 효율성을 떨어트린다면 새로운 이름을 고려해보자

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

• 보편적으로 사용하는 이름이라면 그대로 써도 무방하다.
• 약자를 쓸 때에는 시각적으로 돋보이게 만든다면 기억에 오래 남을 수 있다.

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

• 입력하기 쉬운지, 오타를 낼 가능성이 적은지, 다른 사람에게 말로 전달하기 쉬운지 검토해보는 것이 좋다.

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

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

• 예 (스크린 최대 높이) : int h = 480 (X), int screenHeight = 480 (O)

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

• 예시 :
• { "OK" : true//요청에 대한 성공 실패 여부를 구분합니다. } (X) { "isRequestSuccess" : true } (O)
• 주석이 필요 없이 주석이 의미하는 것을 이름으로 만들어 보자

주석이 필요할 때도 많다.

• 영어 단어를 모든 개발자가 잘 알거나, 문법을 잘 아는 것이 아니다.
• 긍정적으로 생각한다면 주석이 코드의 정확성을 높이고 버그를 줄일 수 있는 계기가 된다.

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

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

• 코드에 표현하지 못한 어떤 의도를 전달해야 할 때는 주석을 쓸 수밖에 없다.
• // letsEatSomething : 밥 먹자는 의미의 함수 letsEatSomething() // 내가 배고픈 상황 (의도를 표현) letsEatSomething() // 네가 배가 고픈 상황 (의도를 표현)
• 개발자가 어떤 의도를 전달하는 이유는 다른 개발자를 위한 것
• 이유를 알려주는 것
• 개발자가 새롭게 발견한 것
• 예상 질문과 답
• 다른 사람에게 보완을 요청하는 것
• 개발자의 속마음을 표현하는 것

주석의 반복

• 코드를 처음부터 읽지 않고, 필요할 때 특정 함수를 검색해서 보는 경우에는 반복된 주석이 필요할 수도 있다.
• 주석이 언제 어떻게 읽히는지에 따라 반복해서 쓸 것인지를 결정해야 한다.

주석의 발췌와 요약

• 주석 내용 중 중요한 것을 뽑아내고 덜 중요한 부분을 빼야 한다.
• 함수의 조건문 내용을 설명하는 주석보다는 조건문의 의미를 주석으로 요약하는 게 더 좋다.

주석도 코드다

• IDE가 발전했어도 주석을 디버깅해주는 기능은 아직 없다.
• 잘못된 주석을 방치하면 주석에 대한 신뢰가 떨어진다.
• 주석도 코드라는 생각으로 항상 꼼꼼하게 다루어야 한다.