Clean Code
로버트 C. 마틴 저/박재호, 이해영 역
#북리뷰
나쁜 코드도 돌아는 간다.
하지만 코드가 깨끗하지 못하면 개발 조직은 기어간다.
개발자라면 꼭 읽는다는 개발자들의 바이블과 같은 이 책은, 비개발자 출신의 팀 선배가 추천해 준 책이다. 개발자의 필독서라는 이 책을 비개발자 출신의 선배가 추천해 줬다는 사실만으로도 이 책을 정독할 이유가 되었다.
실제로 이 책을 3번 읽으면서, 문서를 쓰는 나에게 많은 인사이트를 주었다. 물론 그렇다고 나의 문서 작성 능력이 극적으로 나아지지는 않겠지만, 적어도 방향성을 제시하고 문서 작성 원칙을 다시 한번 정립할 수 있는 계기가 되었다.
이 책 역시 무기 수준으로 두껍고 무거운데(무게가 950g..), 내용은 개비스콘 짤처럼 시원했다. 하지만 절대 쉬운 책은 아니다.
이 책은 좋은 코드를 작성하는 원칙과 나쁜 코드의 특징을 자세하게 설명하고, 책 후반부에서는 앞에서 제시한 원칙에 따라 기존에 쓰인 코드를 분석하고 개선한다.
저자도 들어가면서 다음과 같이 말한다.
이 책을 읽는 동안 마음 고생할 준비를 하기 바란다. 비행기 안에서 심심풀이로 읽어보는 "기분 좋은 책"이 아니다. 열심히, 아주 열심히 독파해야 하는 책이다. (중략) 이 모든 활동에는 시간과 노력이 들지만 그만한 값어치가 있다고 생각한다. (xxxii)
가독성 좋은 깨끗한 코드를 작성하는 일과 독자가 이해하기 쉬운 좋은 문서를 작성하는 일은 참 많이 비슷한 것 같다.
자신의 작품을 조금 더 자랑하자. 함수와 클래스에 조금 더 시간을 투자하자. 더 나은 이름을 선택하고, 큰 함수를 작은 함수 여럿으로 나누고, 자신의 작품에 조금만 더 주의를 기울이자. 주의는 대단한 재능이다. (222)
중요한 포인트 몇 가지만 정리해 보았다.
독자 파악
문서의 독자를 파악하고 독자의 수준을 고려하는 것은 문서 작업에 아주 중요한 부분이다. 거의 모든 TW 콘퍼런스에서 꼭 나오는 이야기다. 밥 아저씨(저자 로버트 C. 마틴의 별명)도 이렇게 말한다. 출발이 같다.
Javadoc에서 @author 필드는 저자를 소개한다. 우리는 저자다. 저자에게는 독자가 있다. 그리고 저자에게는 독자와 잘 소통할 책임도 있다. (17)
내용 구성
독자가 결정되면, 어떤 정보가 있는지 파악한 후 내가 작성하고자 하는 문서의 목차를 구성해야 한다.
정보의 흐름은 논리적이어야 한다. 정보를 쉽게 찾을 수 있도록 내용을 어떻게 구분해야 할지 생각해야 하고, 독자들이 쉽게 따라갈 수 있도록 어떤 순서로 써야 할지 고민해야 한다. 전체적으로 여러 번 들어가는 내용이 있다면, 객체 지향 코드에서처럼 문서 관리 비용을 줄이기 위해 파일을 따로 만들어 관리하는 것도 고려해야 한다.
'3장 함수'에서 저자는 다음과 같은 원칙을 제시한다.
작게 만들어라!
한 가지만 해라!
함수 당 추상화 수준은 하나로!
서술적인 이름을 사용하라!
명령과 조회를 분리하라!
반복하지 마라!
함수는 한 가지만 해야 한다. 그 한 가지를 잘해야 한다. 그 한 가지만을 해야 한다. (44)
'10장 클래스'에서도 단일 책임 원칙(Single Responsibility Principle)을 설명한다.
기술 문서의 구성 역시 그렇다. 가장 낮은 수준의 제목당 한 가지만, 한 가지의 내용을 정확히 전달해야 한다.
진짜 목표는 시스템이라는 이야기를 풀어가는 데 있다는 사실을 명심하기 바란다. 여러분이 작성하는 함수가 분명하고 정확한 언어로 깔끔하게 같이 맞아떨어져야 이야기를 풀어가기가 쉬워진다는 사실을 기억하기 바란다. (62)
제목 작성
문서에는 제목 1, 제목 2, 제목 3 등 내용을 구분하는 제목의 수준이 있다. 각 제목은 내용을 포괄할 수 있는 짧은 명사구 형태로 보통 작성하는데, 쉽게 떠오를 때도 있지만 위에서 언급한 내용 구성이 잘못되었다면, 제목은 복잡하고 길어질 수밖에 없다.
단순히 '듣기 좋은' 충고가 아니다. 소프트웨어 가독성의 90%는 이름이 결정한다. 그러므로 시간을 들여 현명한 이름을 선택하고 유효한 상태로 유지한다. 대충 정하기에 이름은 너무나도 중요한다. (399)
제목 이름
나는 내용을 알지만 독자는 내용을 모른다. 그럼 독자는 제목만 보고 어떤 내용일지 유추할 수 있어야 한다. 책 전체를 흐름대로 읽는 소설이 아닌 기술 문서는 보통 필요한 정보'만' 찾기를 원한다. 그렇다면 제목은 그만큼 명확해야 한다. 한참 지난 후에 내가 쓴 문서를 읽었을 때 나 역시도 찾기 쉬워야 한다.
'2장 의미 있는 이름'에서는 이름을 작성하는 원칙을 설명한다.
의도를 분명히 밝혀라
그릇된 정보를 피하라
의미 있게 구분하라
발음하기 쉬운 이름을 사용하라
검색하기 쉬운 이름을 사용하라
인코딩을 피하라
자신의 기억력을 자랑하지 마라
기발한 이름은 피하라
한 개념에 한 단어를 사용하라
말장난을 하지 마라
의미 있는 맥락을 추가하라
불필요한 맥락을 없애라
제목 형식
제목을 작성할 때는 제목 수준마다 동일한 형식으로 써야, 독자들이 내용을 따라가기에 더 쉽다. 예를 들면, 다음 목차를 보면 글을 쓰는 사람이 아니라도 뭔가 어색한 느낌이 들 것이다.
1. 블로그 작성 Write a blog
1.1 새로 만들기 Creating a new post
1.2 편집하는 방법 How to edit
1.3 삭제 Delete a blog
'5장 형식 맞추기'에서 저자는 다음과 같은 원칙을 제시한다.
적절한 행 길이를 유지하라
가로 형식 맞추기
팀 규칙(스타일 가이드)
스타일 가이드 작성 및 관리
좋은 소프트웨어 시스템은 읽기 쉬운 문서로 이뤄진다는 사실을 기억하기 바란다. 스타일은 일관적으로 매끄러워야 한다. 한 소스 파일에서 봤던 형식이 다른 소스 파일에도 쓰이리라는 신뢰감을 독자에게 줘야 한다. 온갖 스타일을 뒤섞어 소스 코드를 필요 이상으로 복잡하게 만드는 실수는 반드시 피한다. (114)
모든 프로젝트에는 스타일 가이드가 있다. Technical Writing 전공과목 중 스타일 가이드 만드는 방법을 배우고 연습하는 시간이 따로 있을 만큼, 문서에서 스타일 가이드는 중요하다.
이 책의 저자도 일관성 있는 코드 작성을 여러 곳에서 여러 번 강조한다.
어떤 개념을 특정 방식으로 유사한 개념도 같은 방식으로 구현한다. 앞서 언급한 '최소 놀람의 원칙(The Principle of Least Surprise)'에도 부합한다. 표기법은 신중하게 선택하며, 일단 선택한 표기법은 신중하게 따른다. (376)
팀이 정한 표준은 팀원들 모두가 따라야 한다. 실제 괄호를 넣는 위는 중요하지 않다. 모두가 동의한 위치에 넣는다는 사실이 중요한하다. (386)
코드 구조를 잡을 때는 이유를 고민하라. 그리고 그 이유를 코드 구조로 명백히 표현하라. (391)
이 책을 읽으면서 팀원들에게 매번 했던 말이 있다. 책에서 저자가 "아 이 얼마나 아름다운 코드인가"라고 감탄하는데, 왜 이게 아름다운 코드인지 전혀 공감하지 못하는 입장이라 굉장히 많-이 답답했었다. 개발 지식이 0.0001도 없기 때문에 모든 내용을 다 이해할 순 없었지만, 실력이 조금 더 쌓이게 되면 또 읽어보고 싶다. 그땐 더 많은 것을 얻을 수 있을 것 같다.
성장하고자 하는 개발자라면, 또는 나 같은 테크니컬 라이터라면 꼭 한 번은 읽어봤으면 좋겠다.
덧.
보자마자 터지는 첫 장의 삽화다. 내지르는 WTF 횟수는 개발자든, 라이터든 문서를 쓰는 사람이라면 누구한테나 적용되나 보다.
