개발자의 글쓰기_2장

김민성·2023년 7월 3일
naming convention개발자의 글쓰기

개발자의 글쓰기

목록 보기
1/2

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

이 글은 김철수님이 작성하신 "개발자의 글쓰기"의 2장, '개발 시간을 줄여주는 이름 짓기와 주석 쓰기'을 읽고 정리한 글입니다. 저자님께서 정리해주신 목차대로 저 나름의 정리를 해보겠습니다.

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

네이밍 컨벤션을 직역하면 '이름 짓는 관습'입니다.

[1 Q] 무엇의 이름을 짓는 것일까요?
= 개인적으로 코딩이란 개발자가 컴퓨터에게 전달하는 작업 메뉴얼이라고 생각합니다. 그 메뉴얼은 여러 단어로 이루어져 있을 것이기에 그런 '단어'의 이름을 지어주어야 하는 것입니다.

[2 Q] 그럼 이름 짓는 관습은 왜 필요한 것일까요?
= 코딩은 컴퓨터 뿐만 아니라 다른 개발자들과도 소통해야합니다. 이런 소통방식들이 모여서 관습이 형성된 것이고, 개발 사회에 합류하기 위해서 이름 짓는 관습을 지켜야하는 것이라 생각합니다.

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

글을 쓰면서 이름을 짓는 것을 고민하지 않는 이유는 한글에는 정해진 단어들이 있고 그 단어를 사용하면 되기 때문입니다. 그러나 개발어 사전은 따로 없기에 개발하면서 이름을 지어야하는 게 고민인 것입니다. 고민하여서 이름을 짓더라도 다른 개발자가 그 이름을 이해하지 못하면 말짱꽝 이기에 더더욱 고민하게 되는 것입니다.

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

개발어 사전이 없다면 존재하는 '영어 사전'을 활용하면 됩니다.

말하자면 이름 짓기는 창조 과정이 아니라 정해진 원칙으로 적절한 단어를 선택해 조합하는 과정일 뿐이다.

조합으로는 주로 명사, 형용사, 동사가 사용됩니다.

  • 명사 + 명사 + 명사
  • 동사 + 명사 + 명사
  • 형용사 + 명사 + 명사

이 조합으로 이름을 구성하여 무슨 기능인지 간결하게 알리면 됩니다.

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

위에 언급하였듯이 코드 네이밍은 영어를 조합하여 만들어지기에 영어 표기법을 준수합니다.

예를 들어 파스칼 표기법과 카멜 표기법은 영어의 대문자 표기 원칙의 특성을 따릅니다.

  1. 중요하거나 크거나 특정한 것을 가리키거나 제목에 해당하는 명사는 모두 첫 글자를 대문자로 쓴다.
  2. 그런 명사들이 이어질 때는 첫 글자를 모두 대문자로 쓴다.
  3. 명사나 관사가 아닌 동사, 형용사 등은 소문자를 쓴다.

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

파스칼 표기법은 단어의 첫 글자를 대문자로 쓰는 방식으로 주로 클래스, 인터페이스 등에 사용됩니다. 클래스와 인터페이스는 프로그래밍에 있어 고유명사처럼 사용되기에 영어에서 명사 표기법과 동일한 것입니다.

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

카멜 표기법은 첫 단어를 빼고 나머지 단어의 첫 번째 글자만 대문자로 쓰는 방식으로 주로 함수나 변수에 사용합니다. 함수는 동작을 시키는 명령어 개념으로 동사가 먼저 사용되고, 변수는 동사나 형용사로 시작하기에 첫 글자를 소문자로 시작하는 것입니다.

위에 언급했던 영어 표기 조합을 파스칼, 카멜 표기법에 대입하면 아래와 같습니다.

  • 클래스, 인터페이스 = 명사+명사+명사 = 파스칼 케이스
  • 변수, 함수 = 동사/형용사+명사+명사 = 카멜 케이스

상수는 모두 대문자로 쓴다

상수를 모두 대문자로 쓰고 언더스코어(_)로 단어를 연결하는 방식은 상수라는 것을 주의시키기 위한 방법이었습니다. 그러나 현재는 사라지고 있는 관습으로 사용여부는 협업하는 개발자끼리 정하면 됩니다.

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

패키지와 모듈은 클래스나 함수 등을 모은 보관함이라고 보면 됩니다. 이 역시 명사이므로 대문자를 사용해야할 것이지만 컨벤션으로 소문자로 사용되어오기에, 이해가 되지 않더라고 관습을 따라야 합니다.

[3 Q] 관습이 영어표기법 근거에 맞지 않다면 바꿔야하지 않나요?
= 중요한 것은 개발자들간의 소통입니다. 원리원칙을 중시하여 '대문자로 쓰는 게 맞으니까 대문자로 쓸래'라고 해봤자 패키지는 사용되지 않습니다. 로마에서는 로마의 법을 따라야 하듯, 개발 사회에서 정해진 관습은 따릅시다.

BEM 표기법

CSS에서 사용되는 BEM 표기법은 대상__요소--상태를 의미한다.

이는 블로그에서 이미 정리한 바가 있으니 그 글의 링크만 남기고 넘어가겠습니다.

https://velog.io/@msg_0217/CSS-%EB%B0%A9%EB%B2%95%EB%A1%A0OOCSS-BEM-SMACSS

가독성과 소통이 먼저다

네이밍 컨벤션이 존재하는 이유가 가장 중요합니다!

그동안 수많은 개발자가 이렇게 컨벤션을 만든 이유는 가독성과 소통때문이다.

가독성을 위해서는 다양한 방법이 있겠지만 소통이 잘되려면 서로가 같은 컨벤션을 지켜야합니다. 그러므로 협업을 할 개발자끼리는 코딩하기 전에 기본적인 컨벤션 규칙을 정하는 것이 우선입니다.

02 변수 이름을 잘 짓는 법

표기하는 방법은 위에서 배웠습니다. 그럼 이제 어떤 식으로 구성해야하는 지를 알아봅시다.

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

i와 d, 같은 소문자 하나인데 무엇이 다를까요?
i는 integer와 index의 첫글자로 개발 사회에서 관습으로 정해져 있습니다. 즉, 관습으로 개발 사회에서 합의가 되어있다면 사용하면 됩니다. 다른 개발자들이 이해할 수 있기 때문입니다.

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

이름이 왜 검색이 잘 되어야 할까요? 여기서 검색은 개발자들이 작업할 때 ctrl + F로 찾는 것을 의미한다고 생각합니다. 관습적으로 많이 사용되는 단어여야 개발자들이 검색할 때 바로 떠올릴 수 있을 것이고 이는 길이와는 상관이 없는 것입니다. 물론 간결성을 더할 수 있다면 좋겠지요.

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

영어에서 복수형을 나타낼 때 -s나 -es를 사용하기에 당연히 붙여야 영어 표기법을 준수하는 것이 아닐까요? 다시 한번 말하지만 네이밍 컨벤션에서 중요한 것은 개발자간의 소통입니다. 

checkUserNamesUnder2Characters()
checkUserNamesExistsInDB()

복수형을 나타내는 -s가 잘 보이시나요? 가독성을 위해서 저자는 변수명은 그대로 두더라도 함수명에서는 -s대신 array나 list of를 사용하는 것을 추천합니다.

checkUserNameArrayUnder2Characters()
checkListOfUserNameExistsInDB()

여기서 역시 중요한 것은 협업하는 개발자들간 정한 규칙이 통일되어야한다는 점입니다.

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

약어 사용에 대한 찬반이 갈리지만, 역시 중요한 것은 개발자끼리 소통이 가능하냐는 것입니다. 관습적으로 사용되는 약어라면 사용하여도 무방할 듯 하지만, 서로 정하는 것이 가장 좋겠습니다.

중요한 단어를 앞에 쓴다

이름이란 무엇일까요?

다른 것과 구별하기 위하여 사물, 단체, 현상 따위에 붙여서 부르는 말

이름의 정의에서 알 수 있듯이 이름에서 핵심은 다른 것과 구별되는 것입니다. 그러므로 여러 단어를 조합해서 만드는 변수 이름에 첫 단어는 수식어보다는 핵심 명사가 되어야 합니다.

함수 이름 짓는 순서

제가 이 책을 읽은 이유입니다. 어떤 식으로 이름을 작성하는 지에 대해 책의 저자가 친절히 소개해주기에 그 과정을 그대로 보여드리겠습니다.

1. 기능을 한글문장으로 표현한다.

처음에는 한글 문장에서 시작해서 몇 개의 영어 단어 조합으로 끝내는 경우가 많다.

사용자가 이름을 입력하고 등록 버튼을 클릭하면, 시스템이 사용자 이름을 input 태그에서 가져와 이름 입력 여부와 글자 수를 확인 한 후 입력이 안 되었으면 스크립트를 중단하고 input 태그를 활성화해 사용자가 쓸 수 있게 하고, 글자 수가 한글 두 글자 이하면 확인을 요청해 사용자가 확인할 수 있게 한다.

한글로 기이이이이일게 소개한 글에서 이름으로 불필요한 부분을 제거해보겠습니다.

2. 사용자가 하는 일은 삭제한다.

함수는 시스템이 할 일을 나타내는 것이지 사용자가 할 일을 나타내는 것이 아니다.
...
논리적으로 합쳐야 하거나 떼야 할 것을 확인해서 다시 정리한다.

사용자가 이름을 입력하고 등록 버튼을 클릭하면 시스템이 사용자 이름을 input 태그에서 가져와 입력 여부와 글자수를 확인한 뒤 입력이 안 되었으면 스크립트를 중단하고 input 태그를 활성화해 사용자가 쓸 수 있게 하고, 글자 수가 한글 두 글자 이하면 확인을 요청해 ~~사용자가 확인할 수 있게 한다. ~~

3. 남은 문장을 조각낸다.

  1. 사용자 이름을 input 태그에서 가져온다.
  2. 사용자 이름의 글자 수를 확인한다.
  3. 입력이 안되었으면 input 태그를 활성화한다.
  4. 글자 수가 한글 두 글자 이하면 확인을 요청한다.

4. 함수 갯수를 결정한다.(1함수 1업무)

  1. (함수1) 사용자 이름을 input 태그에서 가져온다.
  2. (함수2) 사용자 이름의 글자 수가 2글자 이하면 다음과 같이 처리한다.
    • 만약 글자 수가 0(=null)이면 input 태그를 활성화한다.
    • 만약 글자 수가 1 또는 2이면 사용자에게 확인을 요청한다.

5. 함수 문장을 영어로 바꾸자

  1. get user's name from the text input field
  2. do something if user's name contains under 2 characters

6. 불필요한 단어를 없애자(정관사, 소유격 등)

  1. get user name from input field
  2. check if user name contains under 2 characters

7. 띄어쓰기를 없애고 함수이기에 카멜케이스를 사용하자

  1. getUserNameFromInputField()
  2. checkIfUserNameContainsUnder2Characters()

8. 함수를 사용할 때 의미상 없어도 되는 단어는 없애자

  1. getUserNameFromField() <- input에 사용되기에
  2. checkUserNameUnder2Characters() <- 조건문으로 확인할 것이기에

기능을 보고 한번에 함수명이 나오면 가장 좋겠지만, 익숙해질때까지는 1~8 과정을 천천히 밟으면서 네이밍해보자!

03 좋은 이름의 기준, SMART

한 번에 좋은 이름을 지을 수는 없다

위에서 언급했듯이 한번에 좋은 이름을 짓기는 어렵습니다. 그렇기에 좋은 이름의 기준을 갖고 그 기준에 맞추려는 노력이 필요합니다.

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

그렇다면 좋은 이름이란 무엇일까요?
이는 이름을 짓는 이유와 직결됩니다. 개발에서 이름은 개발자간의 소통을 위해 필수적입니다. 그러므로 개발자들이 많이 사용하는 이름이 좋은 이름일 것입니다.

누구나 이름을 지을 수 있다. 하지만 그 이름이 널리 퍼져 많은 사람이 사용하게 하려면 좋은 이름이어야 한다.

이에 저자는 좋은 이름인지 확인하는 5가지 기준으로 SMART를 제시하였습니다.

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

작업의 크기가 커지게되면 이름을 일일이 기억하지 못할 것이고 필요할때마다 이름을 검색해 사용할 것입니다. 그러므로 검색하기 쉽게 이름을 지어야 합니다.
어떻게 검색하기 쉽게 이름을 지을 수 있을까요? 저자는 고전적 범주화를 이용해 한 단계 상위 범주의 이름을 태그처럼 덧 붙이는 것을 추천했습니다.

예를 들어 에러 메시지와 관련된 이름들 앞에 접두어로 ERROR_를 붙이거나 사용자와 관련된 이름에는 user를 붙이는 것입니다.

같은 접두어를 사용하는 이름이 많아지게 되면 그 접두어 속에서 체계를 형성하여 나누어야합니다. 예를 들면 SERVER_ERROR, INTERFACE_ERROR처럼요.

이 역시 하나의 방법이기에 협업하는 개발자들끼리의 합의가 우선되어야 합니다.

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

저자가 말하는 조합은 개발 언어의 문법과의 조합입니다. 예를들어 html 태그인 경우 title이라는 이름을 활용한다면 h1, h2, p 등 다양한 태그와 함께 조합하여 각각을 구별하기 쉽습니다.

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

이름은 결국 개발자간의 소통 수단입니다. 배(=소통)보다 배꼽(=이름 짓기)이 커지면 안 되듯, 효율적인 이름 짓기가 필요합니다. 여기서 효율이란, 대상을 구별한다는 이름의 목적에 맞는 상황에서만 이름을 지으면 된다는 의미입니다.

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

여기서 중요한 것은 몇 개를 기억하느냐가 아니다. 어떤 이름을 기억해내느냐가 중요하다.

이를 위한 방법으로 저자는 몇가지를 소개합니다.

  • 시청각적으로 완결된 단어
    (TRQWRE vs. QWERTY, BIE vs. BIOE)
  • 이미 널리 알려진 용어

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

자주 사용되거나 중요한 이름이라면 입력하기 쉬운지, 오타를 낼 가능성이 작은지, 다른 사람에게 말로 전달하기 쉬운지 검토해 보는 것이 좋다.

이와 반대로 다음은 입력할 때 틀리기 쉬운 단어로 사용할 때 유의해야 합니다.

  • 연속된 철자
    : successes, classes, committee, parallel
  • 묵음
    : lambda, thumbnail, debt
  • ie/ei
    : chief, receive, retrieve, friends, achieve
  • sion/tion
    : position, commission
  • uous/ous/us
    : continuous, fabulous, genius

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

코드에서 주석은 다른 개발자에게 코드 관련한 내용을 전달할 때 사용됩니다. 예를 들면 함수에 대한 설명을 주석으로 전달할 수 있을 것입니다.

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

만약 이름으로 함수에 대한 설명을 전달할 수 있다면 관련 주석은 불필요할 것입니다.

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

이 부분은 예시로 충분히 설명될 듯 합니다.

[안 좋은 예]

"success": [ // 구독자 추가 성공
],
"update": [ // 이미 있는 구독자, 나머지 필드를 업데이트해야함.
],
"failDeny": [ // 수신 거부 상태의 구독자, 추가하지 않음.
],
"failWrongEmail": [ // 잘못된 이메일 주소 형식, 추가하지 않음.
],
"failUnknown": [ // 알 수 없는 오류로 추가하지 않음.
]

[좋은 예]

"created": [
],
"updatedInformationExceptEmail": [
],
"noCreatedBecauseUnsubscriber": [
],
"noCreatedBecauseWrongEmail": [
],
"noCreatedBecauseUnknownError": [
],

이름의 존재이유에 대해 계속 생각해야합니다. 이름은 개발자와의 소통을 위해 존재합니다. 간결하기만 할 뿐 소통을 위해 주석이 필요하다면 잘못된 이름짓기입니다. 이름만으로 소통이 가능한 선에서 간결성을 더해야합니다.

주석이 필요한 때도 많다

개발자마다의 영어 수준은 다를 것입니다. 오역할 수 있는 이름이라면 주석을 추가하여 코드의 정확성을 높여야합니다.

주석이 제 역할에만 충실하다면 많고 적고는 상관없다.

합리적인 이유가 있다면 사용해야합니다.

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

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

글은 의미를 전달하는 수단이다. 코드도 마찬가지다.

이름에 의도까지 추가하려한다면 이름이 지저분해질 수 있습니다. 그러므로 개발자의 의도는 주석으로 표현하는 것이 좋습니다.

개발자가 어떤 의도를 전달하는 이유는 다른 개발자를 위한 것이다.

아래는 다른 개발자를 위한 주석 예시입니다. 아래 의도들은 주석으로 사용하면 소통에 도움이 될 것 입니다.

[이유를 알려주는 것]

[개발자가 새롭게 발견한 것]

[예상 질문과 답]

[할 일이나 주의, 개선 아이디어를 주는 것]

[다른 사람에게 보완을 요청하는 것]

[개발자의 속마음을 표현한 것]

주석의 반복

반복되는 것이 안 좋은 것만은 아닙니다. 가장 중요한 것은 소통하는 데 충분하느냐입니다. 그 이상으로 반복된다면 줄이는 것이 좋습니다.

주석의 발췌와 요약

발췌는 중요한 것을 뽑아내는 것이다. 중요한 것을 뽑으려면 덜 중요한 것을 빼야 한다.

소통에서 중요한 것은 가독성과 소통이라고 얘기해오고 있습니다. 소통하기에 충분하다면 가독성을 위해서 발췌, 요약하여 주석을 줄여나가야 합니다.

주석도 코드다

주석을 경시하는 개발자들이 있습니다. 그러나 주석 역시 개발자간의 소통을 위한 도구이므로 코드와 목적이 동일합니다.

불필요한 주석은 없애고, 꼭 필요한 주석은 코드처럼 뤄야 합니다.

느낀점

가장 중요한 것은 존재 이유라고 생각합니다. 존재하는 이유에 맞게 사용하고, 존재하기에 충분한 이유가 있다면 존중하며, 존재할 이유가 없다면 줄여야 할 것입니다.
코딩(개발자간 소통),이름(구별)과 주석(의도 전달)의 존재 이유를 항상 생각하며 사용하겠습니다.

참고자료

  • '개발자의 글쓰기' 2장
profile
김민성
'WHY'를 묻고 reason을 공부하는 개발외ㅓ인
다음 포스트

개발자의 글쓰기_3장

1개의 댓글

comment-user-thumbnail
신유빈
2023년 7월 6일

유용한 글 잘 읽고 갑니다!

답글 달기