[책 후기] 개발자의 글쓰기
- 저자: 김철수
- 출판사: 위키북스
- 책 링크: http://www.yes24.com/Product/Goods/79378905
🙂 읽게 된 계기
회사에서 개발자들끼리 소소한 책읽기 모임을 가졌다. 첫 모임이니만큼 가벼운 책으로 시작하고자 '개발자의 글쓰기'가 선택되었다. 진행 방식은 주에 한시간 정도 시간을 갖고, 그 자리에서 책을 읽은 뒤 곧바로 의견을 나누는 식이었다. 미리 준비할 게 없어서 부담없이 참여할 수 있었다.
😄 읽고 나서
책을 읽다보면 당연하게 여겼던 것들, 공감되는 것들도 많았지만 나는 이거보단 저게 더 깔끔해보이는데? 저게 더 낫지 않나? 같은 생각이 드는 경우도 많았다. 이 글에서는 몇 가지 공감갔던 내용과 유용하겠다 싶었던 소소한 팁들 등을 소개해보고자 한다.
변수 이름 짓기
이름 짓기는 무에서 유를 창조하는 것이 아니라 기존 단어를 적절하게 조합하는 것이다.
문뜩 작년 일이 생각났다. 블랙잭이라는 게임을 Java 코드로 만들어내는 미션을 진행할 때였다. 블랙잭 게임 결과, 즉 승자는 누구고 패자는 누구다 같은 결과를 도출해내는 메서드가 있었는데 이름을 한참 고민했던 기억이 난다. 처음 생각난 이름은 getResult였는데, 개인적으로는 단순히 값을 가져오는 용의 getter가 아닌 특정 로직을 수행해 값을 반환하는 메서드에는 getXXX의 이름을 붙이는 것을 좋아하지 않는다. 다른 이름을 고민하다 '도출하다'의 의미로 'elicit'이라는 영단어를 찾아냈다. 리뷰어가 어떤 의미인지에 대한 코멘트를 달았던 것 같다. 정말 생소한.. 나조차도 처음보는 단어였기 때문에 아 다른 사람이 보기에도 이건 아니구나, 싶어서 고쳤던 기억이 난다. 왜 'elicit'은 부적절한 단어였을까? 블랙잭이라는 도메인에서도 전혀 등장하지 않았고, 기존 코드에 존재했던 것도 아닌 '전에 없었던 새로운 단어'를 사용했기 때문이 아닐까 싶다.
용어와 내용을 일치시키기
글과 그림의 내용을 일치시키자.
나는 기술 글에서는 '용어를 통일하는 것'이 정말 중요하다고 생각한다. 예를 들어 관계형 데이터베이스의 개념에 대한 설명하는 글이 있다고 가정해보겠다. '관계형 데이터베이스'는 '데이터베이스', 'DB', 'Database', 'RDB' 등의 다른 표현을 사용할 수도 있다. 한 글 내에서 이 모든 표현을 다 사용한다고 생각하면 매우 복잡스럽다. 관계형 데이터베이스를 알지 못하는 사람이라면 갑자기 튀어나온 단어인 RDB의 뜻을 찾아보다가 아, 이게 관계형 데이터베이스의 약어였구나! 같이 찾아보는 시간을 가져야만 글을 이어서 읽을 수 있다.
글과 그림의 내용을 일치시키는 것도 이것과 동일한 맥락이라고 생각한다. 다른 사람에게 더 쉽게 이해시키기 위해 '그림'을 이용하는건 정말 편리하다. 특정 개념을 처음 접한 사람들에게도 글만 읽을 때보다는 그림과 함께 같이 글을 읽으면 더 쉽게 이해할 수 있다. 하지만 그림과 글의 내용이 다르다면? 오히려 혼란을 야기하는, 없는게 더 나은 그림이 되고만다.
글쓰는 사람 입장에서는 글의 내용이 바뀔때마다 그림을 바꿔야한다는 것 자체가 굉장히 불편하고 귀찮은 일이다. 해서 개인적으로는 글을 모두 수정한 다음에 그림을 추가하거나, 테이블로 대체할 수 있는건 블로그에 있는 표 기능으로 대체하고 그림을 아예 빼버리는 방법도 선택하고는 한다.
주석은 나쁜 코드일까?
주석이 필요한 때도 많다.
"주석이 없어도 이해할 수 있어야 좋은 코드다."라는 말이 정말 많다. 나도 어느정도 동의하지만 "주석이 있는 코드는 나쁜 코드다"라는 말에는 동의하지 못한다. 우리의 모국어는 영어가 아니라 한국어다. 나를 포함한 많은 개발자들이 영어에 익숙치 않다. 혼란을 야기할 수 있는 메서드나 굉장히 복잡한 비즈니스 로직을 가진 코드라면 오히려 주석을 추가하는 것이 나을수도 있다. 책에서 제시한 예제가 인상깊어 공유한다.
checkUsernameUnder3Characters()
위 메서드 이름을 보면 사용자 이름의 길이를 검증하는 로직일 것이라고 유추할 수 있다. 여기서 under3Characters라는 표현은 3글자 '이하'를 의미하는 것일까 3글자 '미만'을 의미하는 것일까? 정답은 3글자 '미만'이다. 이하같은 경우에는 'and under', 'or less', 'or below'가 정확한 표현이다. 다음과 같은 주석을 추가한다면 사람들은 주석을 읽느라 코드 읽는 시간은 더 길어지겠지만, 로직을 헷갈릴 일은 훨씬 줄어든다.
checkUsernameUnder3Characters() // 사용자 이름이 3글자 이하인지 검증
서로를 이해하기
가진 것이 망치 뿐이면 모든 것이 못으로 보인다.
처음에는 이 문장의 뜻을 오해했다. 디자이너는 디자이너의 시선으로, 기획자는 기획자의 시선으로, 개발자는 개발자의 시선으로만 본다. 즉, 문제에 대한 단편적인 부분만 바라보게 되니 내 입장만 고수하지 말라는 것을 의미하는 건가? 싶었는데 '모두가 각자 자기 위치와 입장에서 최선을 다하는 것 뿐이다.'라고 표현한 말이 인상깊었다. 비슷한 의미일지언정 "~하지마라"는 식의 표현보다는 좀 더 긍정적인 표현이 훨씬 좋아보였고 다르게 다가왔다.
😊 마치며
얇은 책이라 가볍게 읽기 괜찮은 책이라고 생각한다. 이미 글쓰기를 많이 해봤거나 글쓰기에 대한 자신의 주관이 뚜렷한 사람들이라면 와닿지 않는 내용이 많을수도 있겠지만, 내 글에 대해 제 3자의 피드백이 필요한 사람 또는 글쓰기를 어떻게 시작할지 모르겠는 사람들이 읽기 좋을 것 같다.
모든 내용을 읽을 필요는 없다. 내가 필요한 글쓰기와는 필요없는 내용이 있을수도 있다. 내게도 불필요한 내용들도 있다보니 적당히 훑고 필요하다고 생각되는 부분들만 읽었다. 예를 들어 SI 제안서 쓰기 같은 경우에는 지금 당장 나에게 필요하지 않을 뿐더러 지금 회사에 다니면서는 계속 작성할 일이 없다고 생각했다. 나중에 제안서를 써야할 때가 온다면 그때가서 찾아봐도 된다고 생각한다.
저자 분도 말씀하신 내용이지만 모두에게 정답인, 올바른 글에 대한 기준은 딱히 없다. 개발과 마찬가지로 그때그때 상황에 따라 필요한 형식으로 작성하면 된다. 책을 읽으면서 해당 책의 내용을 그대로 흡수하기 보다는 이런 식의 글쓰기도 있구나, 이 부분은 나한테 적용해도 좋겠다 식으로 부분 부분만 흡수하면 더 좋을 것 같다.