프로그래머의 글쓰기 고민 끝! 개발자의 글쓰기

안녕하세요 😀

 유로띠 입니다 😉

 

 

 

 

 

개발자의 글쓰기

---

MIL (Month I Learned)

 

책을 읽고 개인적으로 중요하다고 생각되는 부분이나 소개하고 싶은 내용만 작성하였습니다.

소개하고자 하는 범위

✏️  1장 개발자가 알아야 할 글쓰기 기본

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

 

😉 책에서 기억하고 싶은 내용을 써보세요.

 

개발자의 글쓰기는 정확성 간결성 가독성이 중요하다. 👍

 

 

 

1장. 개발자가 알아야 할 글쓰기 기본

 

영어 단어 선택과 외래어 표기법

개발을 하다 보면 영어와 친해져야 한다. 

개발을 하다 보면 반대가 되는 단어를 선택해야 할 때가 많이 있다.

 

🟢  반대 말

show(보여주다)의 반대로 어떤 것을 사용하면 좋을까? 바로 hide(감추기)가 좋다. hide 대신 invisible을 쓰면 안 된다. 이것의 반대말은 visible이기 때문이다.

 

🟢  비슷한 말

반대말뿐만 아니라 비슷한 말도 많이 있다.

중단이라는 의미를 가진 영어 단어는 stop, end, finish, pause, suspend, hold 등 다양하게 존재한다.

 

endUserRegister(); // 사용자 등록을 종료한다.

이다음에 다시 사용자를 등록하는 함수는 어떻게 작성해야 할까? startUserRegister 🤔

//사용자를 새롭게 등록하려면 begin을 사용한다.
beginUserRegister();

end는 완전히 중단되어 재시작할 가능성이 전혀 없다는 뜻이기 때문에 반대말은 begin을 사용해야 한다.

 

비슷한 예로 이번 달 말을 뜻하는 endOfMonth를 사용하면 이번 달 초를 뜻하는 단어를 beginOfMonth를 사용해야 한다.

그런데.. Date lib Docs를 보면 endOfMonth의 반대로 startOfMonth를 사용하고 있다.. 😳

 

stopUserRegister(); // 사용자 등록을 중단한다.

// 다시 재개하려면 start나 restart를 사용한다.
startUserRegister(); 
restartUserRegister();

stop은 잠심 중단하는 것이어서 언제든 재시작할 수 있기에 반대말은 start, restart를 사용해야 한다.

 

 

finishUserRegister(); // 사용자 등록을 종료한다.

finish 다음에 다시 사용자를 등록하려면 어떻게 해야 할까? 이 함수를 실행한 후에 다시 사용자 등록을 요청하면 에러가 발생해야 한다.

finish는 끝장을 본 상태여서 재시작을 고려할 필요가 없기 때문이다.

 

 

🟢  가져오기

get은 어떤 값을 돌려받아서 반환하는 함수에 사용한다.

getCourseById(id: number);

 

return은 함수 이름에 사용하지 않는다. 

returnCourseById(id: number); //???

왜일까? (대부분 아시겠지만..)

return은 함수 안에서 제어에 사용되며, 또한 return의 주체는 객체이므로 함수에 return을 쓰면 자기가 자기에게 돌려주는 이상한 루프에 빠진다.

 

🟡  비슷한 말

✅  retrieve : 검색해서 가져온다 / 검색에 무게가 실린다면

✅  acquire : 독점한다 / 다른 함수가 가져가지 못하게 독점하고자 할 때.

✅  fetch : 현재 값을 가리키는 포인터가 다음 값으로 이동한 것을 가져온다

 

 

🟢  등록

✅  register : 이미 정해진 틀에 값을 집어넣는 것.

✅  create :  정해진 틀이 없으므로 먼저 틀을 만들 때.

 

어떻게 하면 이해할 수 있을까 예시를 작성해 보았는데.. 정확한 지는 모르겠습니다 🙏 (지적 부탁드려요!!)

createCourse(); // 코스 생성

createProduct(); //상품 생성

// 강의, 상품이 존재하는 주어진 틀에서 수강신청을 진행
registerEnrollment(); //수강신청

 

 

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

 

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

변수 이름부터 시작해서 함수, 클래스, 파일, 디렉터리, 데이터베이스 칼럼, 프로젝트 이름까지 정해야 합니다.

 

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

 

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

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

 

오픈소스의 네이밍 특징들이란 블로그 글을 보면 몇 가지 중요한 네이밍 규칙을 데이터로 증명했다.

오픈소스의 네이밍 특징들

 

자바 네이밍 컨벤션을 철저히 준수한다.

클래스는 UpperCamelCase

함수와 변수는 lowerCamelCase

상수는 UPPER_DELMITER_CASE

 

네이밍은 클래스(20자), 함수 (18자), 변수(13자) 해서 평균 16글자 평균 3개 단어로 조합된다.

 

품사는 주로 명사, 동사 , 형용사의 조합니다.

명사 + 명사 + 명사

동사 + 명사 + 명사

형용사 + 명사 + 명사 등

 

 

변수 이름을 잘 짓는 법

 

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

요즘은 개발 환경이 아주 많이 좋아져서 변수 이름을 처음부터 끝까지 모두 입력하는 경우는 거의 없다. 첫 글자 몇 개만 입력해도 개발툴이 자동으로 변수를 찾아서 제시한다. 이제는 변수 이름을 타이핑하지 않고, 검색해서 찾아 선택하는 방식으로 개발하기 때문에 변수 이름의 길이와 오탈자의 상관관계는 이제 없고 검색이 잘되는 이름으로 작성하면 좋다.

 

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

약어를 만드는 좋은 방법은 보편성을 기준으로 정하는 것이다. 회사나 업계에서 많이 사용하는 약어라면 코드에 사용하는 것이 좋다.

 

HyperTextMarkupLanguage -> HTML
User Interface -> UI
temp -> Temporary
document -> doc
parameter -> param
argument -> arg

 

🟢  중요한 단어는 앞에 쓴다.

변수 이름을 여러 단어로 조합할 때는 순서를 잘 정해야 한다. 예를 들어 총 방문자 수를 나타내는 변수를 보통 totalVistor로 그대로 번역해 변수로 사용하곤 한다. 하지만 이 변수를 다시 사용할 때는 total로 검색을 시작하는 경우보다 visitor로 검색을 시작하는 경우가 더 많을 것이다. 따라서 total이라는 수식어보다는 본래 의미를 뜻하는 visitor를 앞에 쓰는 것을 추천한다.

 

int totalVisitor -> visitorToal
int totalPlayTime -> playTimeTotal
int numberOfToalVIP -> vipCount

물론 요즘 개발 도구는 검색할 때 해당 단어가 포함된 클래스나 변수를 다 찾아준다. 그래서 단어를 조합해 이름을 지을 때 순서가 그다지 의미 없을 수도 있다. 다만 중요한 것이 앞에 와야 한다는 기본 원칙은 지키자.

 

 

좋은 이름의 기준, SMART

 

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

 

지금은 누구나 사용하는 유튜브(youtube)는 you + tube를 붙인 말로, you = 당신, 사람들을 뜻하고 tube = 옛날 진공관 텔레비전을 흔히 일컫는 말이다.

하지만 이 이름이 나올 때까지 창업자들은 종일 고민했다. 나름의 기준도 있었다.

✅ 듣기에 좋고 외우기도 쉽고 두 음절이어야 한다.

✅ 알파벳 7자 이내여야 한다.

✅ 두 음절에는 각각의 의미가 있어야 하며, 하나는 소셜, 하나는 미디어의 의미를 담아야 한다.

 

 

좋은 이름이 가진 공통의 기준은 다음과 같다.

✅ easy to Search : 검색하기 쉽고

✅ easy to Mix : 조합하기 쉽고

✅ easy to Agree : 수긍하기 쉽고

✅ easy to Remember : 기억하기 쉽고

✅ easy to Type : 입력하기 쉽고

 

 

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

 

이름을 잘 지으면 주석을 대폭 줄일 수 있다. 이름이 주석이 할 일을 대신하기 때문이다.

 

처음부터 변수 이름을 최대 높이로 지으면 의미가 충분히 전달되므로 주석을 쓸 이유가 없다.

// 스크린 최대 높이를 480으로 지정함
int h = 480 (🙅‍♂️)


int screenHeightMax = 480 (🙆‍♂️)

 

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

 

코드는 의미를, 주석은 의도를 표현하자.

개발자가 어떤 의도를 전달하는 이유는 다른 개발자를 위한 것이다. 코드를 왜 이렇게 작성했는지 설명하고 뜻밖의 발견을 제시하거나 새로운 아이디어를 보여주거나 어떤 방법이 더 좋은지 알려주는 것은 모두 다른 개발자를 배려하는 마음이다.

 

🙋‍♂️ 이유를 알려주는 것

// 로딩 속도는 2배 빨랐다.
// user-agent 를 credential 로 사용한다. token 발급 시점의 OS, browser 를 access token 에 기록한다.

 

🙋‍♂️ TODO: 아직 하지 않은 일 = 할 일

// TODO: 무통장 입금 예정 기간이 지난 트랜젝션의 상태를 변경해 주어야 합니다.
// TODO: 간편로그인 서비스 추가되면 개선 필요

 

🙅‍♂️ XXX: 주의! 여기 큰 문제가 있다.

// XXX: 논리적인 문제가 있음 code 가 중복되었을 경우 어떻게 함?

 

🧑‍🔧 FIXME: 오작동을 일으킨다고 알려진 코드 = 다른 사람에게 보완을 요청

// FIXME: 비과세에서 먼저 할인. 할인액이 비과세액을 넘을때만 과세부분에서 할인. (가능한 과세금액은 건들지 않음)

 

🤔 HACK: workaround = 임시적인 해결책

// HACK: 이 스크립트는 받는 페이지에서 처리하는 것이 낫다.

 

😏 개발자의 속 마을을 표현한 것

// 솔직히 이 코드는 마음에 안 든다.
// 팀의 컨벤션만 아니라면 클래스명부터 바꿨을 것이다.

 

 

🟢 주석도 코드다

비슷한 코드와 주석을 반복하다 보면 복사에서 붙여 넣은 뒤 수정하는 과정에서 실수할 때가 종종 있다.

이때 잘못 쓴 코드는 디버깅으로 바로잡을 수 있지만, 잘못 쓴 주석은 개발자가 신경 쓰지 않으면 결코 바로잡을 수 없다.

아무리 IDE가 발전했어도 아직 주석을 디버깅하는 기능은 없다. 그래서 잘못된 주석이 늘어나고, 그러다 보니 개발자가 주석을 믿지 않는 풍토가 생기고, 그러니 더 주석에 신경 쓰지 않게 된다.

주석의 악순환에서 벗어나는 가장 좋은 방법은 주석도 코드라고 생각하는 것이다. 불필요한 주석은 없애고, 꼭 필요한 주석은 반드시 코드처럼 다뤄야 한다.

 

 

 

 

🧐 오늘 익은 소감은? 떠오르는 생각을 가볍게 적어보세요

✅  혼자 일하는 것이 아닌 이상 수많은 사람들과 협력을 하려면 정확하게 간결하게 가독성 있게 글을 쓰는 것이 중요하다고 생각된다.

✅  영어와 친해져야 하는 말에 공감이 가고 그동안 그냥 사용해왔는데 비슷한 말, 반대말에 대해 다시 한번 생각해 본다. 

✅  그래도 아직 변수 네이밍은 어렵다..

 

 

🙋‍♂️ 궁금한 내용이 있거나, 잘 이해되지 않는 내용이 있다면 적어보세요.

⭐️  개발자의 글쓰기

개발자의 글쓰기 - YES24

⭐️  주석 태그

Comment (computer programming) - Wikipedia