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

Subin·2023년 7월 7일

개발자의 글쓰기

목록 보기

2/7

📝 김철수님의 '개발자의 글쓰기'를 읽고 정리한 글입니다. 문제가 될 경우 삭제 조치하도록 하겠습니다.

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

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

개발자는 변수 이름부터 함수, 클래스, 파일, 폴더 등… 아무리 작은 프로그램이어도 이름 지을게 투성이라고 한다.

그러면서 Quora, Ubuntu 포럼에서 개발자에게 설문한 자료를 제시하면서 앞의 말에 힘을 실어주는 것을 보고 이런 사소한 점도 글 쓰는 방법이라고 느꼈다.

아무튼 개발자는 궁극적으로 코드에 주석을 최소화하며 누가 봐도 쉽게 이해할 수 있는 코드를 작성하는 것이며 여기서 큰 작용을 하는 게 네이밍이다.

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

개발자들이 이름 짓기를 어려워하는 이유는 무에서 유를 창조한다는 생각 때문인데 이는 아니라고 한다. 라이브러리를 사용하는 것처럼 기존 방식을 차용해서 새로운 이름을 짓는 경우가 대부분이라고 한다.

한국인 아이의 이름을 나카무라라고 짓지는 않는 것처럼 말이다.

성은 부모에게 물려받고 형제와 돌림자를 쓰는 경우도 있어 이 2개를 조합한 뒤 새로 만드는 게 네이밍의 기본인 것이다.

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

1.2에서 아이의 이름 짓기처럼 코드 네이밍 컨벤션은 영어 표기법을 상속받았다고 한다. 대표적으로 파스칼 표기법과 카멜 표기법은 영어 대문자 표기 원칙을 상속받았다.

파스칼 표기법

모든 단어에서 첫 글자를 대문자로 쓰는 방식으로 주로 클래스, 컴포넌트명과 같이 프로그래밍에서 가장 주요하고 상위 개념에 고유명사처럼 특정되는 것들에 사용된다.

interface Menu
class CoffeeMenu implements Menu

카멜 표기법

첫 단어를 제외한 나머지 단어의 첫 글자만 대문자로 쓰는 반식으로 주로 함수나 변수에 사용된다.

영어는 명사가 아닌 경우 첫 글자를 소문자로 쓰기에 동사인 함수, 형용사인 변수는 카멜 표기법을 사용한다.

let totalCount = 0;
function orderCoffee();

상수

영어 표기 원칙에서 상수는 대문자로 쓰지 않는데 프로그래밍에서는 전부 대문자 로 쓰고 언더바(_)로 단어를 연결한다.

const COFFEE_MAX = 10

상수는 값이 변하지 않는 걸 강조하고 주의하기 위해 대문자로 가독성을 높였는데 이게 정답은 아니라는 말을 하면서 팀원과의 협업 시 통일하는 게 좋다고 다시 한번 강조한다.

패키지와 모듈

패키지와 모듈은 클래스나 함수보다 더 상위개념인데 소문자를 사용한다. 여러 클래스나 함수를 담아놓은 박스에 불과하기에 주로 보는 코드는 아니어서 그렇다고 한다. 패키지와 클래스 이름을 혼동할 수 있기에 소문자로 하는 게 실용적이기도 해서 컨벤션으로 자리 잡았다고 한다.

kr.co.wikibook.android.developerwriting
import developerwriting

BEM

BEM(Black Element Modifier) 표기법은 대상의 요소나 부분을 의마할 때는 언더바 2개(__) 대상이나 요소의 상태나 속성을 의미할 땐 바 2개(--) 로 연결한다.

.form {}
.form__button {}
.form__button-disabled {}

1.4 가독성과 소통이 먼저다

위의 표기법은 사람들이 주로 사용하는 표기법이지 중요한 것은 이러한 표기법을 쓰는 이유다 이유가 있다면 다르게 써도 상관은 없다고 한다. 하지만 컨벤션을 사용함에 있어 왜 이렇게 쓰는지 이유는 알고 써야 한다고 한다. 컨벤션은 이미 개발자들 사이에서 검증되었기에 믿고 그냥 무작정 따라 쓰지 말란 뜻이다.

그래서 1장에서부터 강조했던 말이 나오는데, 개발하기 전에 컨벤션 규칙을 정하는 게 우선이라고 한다. 개발은 혼자 하는 게 아니기 때문이다. 1인 개발도 추후에 팀원이 합류할 가능성이 있다.

아무튼 컨벤션을 정하면 가독성과 소통을 잡을 수 있기에 컨벤션에 신경 써야 한다.

이미 검증된 에어비앤비 컨벤션, 토스 컨벤션이 주로 사용되는 가운데 협업에 도움이 되도록 남들이 익숙한 컨벤션을 익혀두는 게 좋겠다고 생각했고 왜 이러한 표기법을 채용했는지 생각하는 시간을 가지면 좋겠다고 느꼈다.

2. 변수 이름을 잘 짓는 법

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

가장 많이 쓰는 변수 이름은 i, LOG, result라고 한다. i는 정수르 뜻하는 integer와 지수인 index의 첫 글자이므로 반복문의 카운터나 배열 인덱스로 i를 많이 사용해도 이상할 게 없다. 그 형제인 i, j, k도 어색하지 않다. x, y 좌표도 같은 경우다 관습적으로 이미 박혀있는 것들이기에 사용해도 나쁘지 않다.

day를 뜻한다고 생각하고 d로 이름을 지엇다면 이는 좋지 않다.

day도 someday, today, thisDay, fianlDay.. 더 구체화시켜야 한다.

int today
int thisMonth
int daysSinceCreated

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

여기서는 메모장, vim에서 개발하던 예전 개발 환경에서는 백화점을 방문한 VIP 고객 수의 변수를 굳이 numberOfTotalVeryImportantPersons이라고 안 하고 VIPS라고 썻는데 이는 이유가 있었다고 한다. 그냥 VIPS라고 사용하고 문서에 해당 설명을 등록하는 게 더 용이했기 때문이다.

접두어도 마찬가지라고 하는데 m, n, is btn, img등의 헝가리안 표기법은 통합개발환경이 발전함에 따라 거의 레거시 되었다고 한다.

그래서 내가 느낀 건 어차피 해당 변수, 함수들을 개발 환경에서 자동완성으로 검색해 주기 때문에 긴 이름이나 짧은 이름은 신경 쓰지 말고 버튼들은 항상 btn을 붙이자는 식으로 규칙을 정해 사용하면 좋을 거 같다.

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

배열을 UserNames로 s를 붙이면 쉽게 알아볼 수 있을 것이다. 하지만 함수명 중간에 사용할 땐 눈에 잘 띄지 않는다.

checkUserNamesExistsInDB();

그래서 변수명은 그대로 UserNames로 하더라도 함수명에서는 array나 listOf를 쓰는 게 더 나을 수 있다고 한다.

checkUserNameArrayUnder2Characters();

방법은 여러 가지이며 정답은 없다고 한다. 이는 이 책에서 항상 말하는 팀원과의 규칙을 통일하면 된다고 한다.

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

저자는 약어를 일부 허용하는 게 좋다고 한다. Amazon Web Service Simple Storage Service를 AWS S3라고 부르는 것처럼 이미 사람들 사이에서 보편적으로 사용되는 약어들이 너무 많다. 약어를 사용하되 사람들이 보편적으로 이해할 수 있는 단어를 선택해야 할 것이다.

2.5 중요한 단어를 앞에 쓴다

변수 이름을 여러 단어로 조합할 땐 순서가 중요하다.

총 방문자 수를 나타내는 변수를 보통 totalVisitor로 번역해 사용하곤 하는데, 해당 변수를 검색할 때 total를 검색하기보단 visitor로 검색을 시작하는 경우가 많을 것이다. 따라서 total이라는 수식어보단 본래 의미를 뜻하는 visitor를 앞에 쓰는 걸 추천하고 있다.

let visitorTotal;

2.6 함수 이름 짓는 순서

함수의 기능을 문장으로 나열
불필요한 문장 제거
영어로 변환
불필요한 단어 제거
띄어쓰기 없애고 카멜 케이스 사용
함수 사용 시 의미상 필요 없는 단어 제거

3. 좋은 이름의 기준, SMART

가게가 개업하면 공기주입기에 연결되어 있는 키 큰 사람 모양의 춤추는 인형을 갖다 놓는다. 이 이름의 변화를 설명하면서 시대에 따라 이름이 바뀌고 한 번에 좋은 이름이 될 수 없다는 것을 알려주고 있다.

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

easy to Search

고전적 범주화를 이용해 한 단계 상위 범주의 이름을 태그처럼 덧붙인다. 예를 들어 소나무, 감나무, 배나무처럼 나무라는 이름으로 범주화하면 된다.

서버 응답시간이 초과될 시 SERVER_TIMEOUT이라는 상수, 변환하는 값이 없다면 NO_RESULT를 사용한다면 검색하기 어려울 것이다. 앞에 ERROR를 붙이면 검색이 용이할 터이다.

ERROR_SERVER_TIMEOUT
ERROR_NO_RESULT

여기서 접두어를 너무 가지면 SERVER_ERROR, INTERFACE_ERROR 과 같이 에러 구분 체계를 만들면 된다.

easy to Mix

css 작성을 예로 들면서 h1, sapn과 같은 시멘틱 태그를 이용해 h1.titme {…} 로 속성보단 상위 개념인 개념을 이용하는 게 좋다고 한다.

easy to Agree

i, j, k와 i,j,k 대신 긴 이름을 사용하는 것에 관점 차이를 설명했는데 상황에 따라 팀원이 납득이 가도록 이름을 효율적으로 지어야 한다.

easy to Remember

시청각적으로 이름을 지으면 기억하기 쉽다. 하지만 시각적으로 좋지 못한 SSG를 쓱이라고 부르는 것처럼 광고로 인해 사람에게 익숙해지면 예외가 발생하긴 한다.

또한 이미 주로 사용되는 용어들을 바꾸지 않고 그냥 쓰는 게 효율적이라고 한다.

easy to Type

입력할 때 자주 틀리는 단어의 예

연속된 철자 : successes, classes
묵음 : lambda, debt
ie/ei : chief, receive
sion/tion: position, commission
uous/ous/us : continuous, genius

이렇게 오타가 잘 나는 단어들은 그냥 줄임말로 표기하는 것도 나쁘지 않은 방법이라고 한다.

항상 검토하고 신경써야 한다.

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

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

// 스크린 최대 높이
int h = 480

위는 변수 h의 값이 뭔지 주석으로 설명해야 하는 코드이다.

하지만 아래와 같이 지정하면 변수 이름만으로 의미가 충분히 전달되므로 주석이 필요 없다.

int screenHeightMax = 480

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

항상 주석 없이 코딩하는 연습을 하면 자연스레 변수 이름으로 누구나 기능을 유추할 수 있게 네이밍을 하게 될 것이다.

4.3 주석이 필요한 때도 많다.

영어를 잘하는 개발자, 못하는 개발자가 있다고 하면 updatedInformationExceptEmail 를 해석하는데 Except라는 단어를 몰라 해석이 어려울지도 모른다. 그렇기에 주석을 달면 미연에 방지가 되어 도움이 되기도 한다.

이렇게 주석이 무조건 필요하지 않다고 생각하면 안 된다. 주석으로 인해 코드의 정확성과 일의 효율이 올라간다고 한다.

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

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

글은 의미를 전달하는 수단처럼 코드도 마찬가지이다. 하지만 밥을 먹자는 의미를 가진 함수의 이름을 letsEatSomething() 라고 지었다고 해도 해당 함수 작성자는 심심하다. 밥 먹자 라는 의미인데 다른 팀원이 심심하지 않고 배고플 때 해당 함수를 사용하면 의미가 없어진다. 그렇기에 의도를 전달해야 하는 경우 주석을 달아야 한다. 이는 팀원을 배려하는 행동이다.

// TODO, // HACK 과 같은 주석도 자주 사용한다.

5.2 주석의 반복

개발 가이드 문서에서 주석이 반복되는 경우가 많은데 이는 이유가 있기 때문이다.

그 이유는 개발 가이드 문서를 다 읽지 않고 해당 기능만을 읽는 사람이 많기에 원하는 기능에 검색해서 들어갔을 때 해당 설명을 봐야 하기 때문이다. 이렇게 상황에 따라 주석의 쓰임새가 다르다.

즉 프로젝트에서는 주석을 반복하지 않고 개발 가이드 문서에서는 반복해서 쓰는 게 좋다고 한다.

5.3 주석의 발췌와 요약

너무 TMI 설명으로 주석을 달지 말고 간단 명료하게 주석을 달면서 코드로 의도를 파악할 수 있게 하면 된다.

// 초코 10개와 푸딩 10개를 먹으면 레벨업
if(choco >= 10 && puding >= 10){
	level++;
}

// 레벨업 조건이 되면 레벨업
if(choco >= 10 && puding >= 10){
	level++;
}

if(choco >= 10 && puding >= 10){
	level++;
}