[책쓰법] #10 예제코드 만들기
들어가는 글: 거의 두 달만의 글이고 올해(2018년)의 첫 글입니다. 재미있게 봐주세요. 최근에는 번역3호와 번역4호를 연속적으로 초벌 번역하느라 정신이 없었네요. 당분간은 책도 읽고 새로운 생각으로 머리를 채워보려고 합니다.
1. 예제코드는 언제 만들까?
앞서 출판 계약을 하고 첫장을 무사히 집필하여 샘플 원고도 서로 확인하고 이제 본격적으로 글쓰기를 해보려고 합니다. 개발 서적이 일반 인문/교양 서적과 다른 가장 큰 것은 "예제 코드"가 있다는 것이죠.
집필에 있어 예제 코드는 언제 만들어야 할까요?
제가 그동안 들었던 사례들을 보면 다음과 같이 구분할 수 있습니다.
1) 예제 코드가 미리 준비되어 있는 경우
2) 본문을 만들면서 예제 코드를 준비하는 경우
3) 전체 프로젝트를 목표로 순서대로 준비하는 경우
이번 글에서는 위의 세 가지 경우를 알아보겠습니다.
2. 준비된 예제 코드
예를 들어 어떤 주제를 강의 하고 있거나 혹은 경험이 많은 경우 평소에 필요한 예제 코드를 모아 놓는 것이 중요합니다. 요즘 저자들은 책의 예제 코드를 github에 올려 놓아 공개하는 경우가 많습니다.
예를 들어 제가 번역했던 <그레이들 레시피>는 예제 코드 저장소는 다음과 같습니다.
https://github.com/kousen/GradleRecipesForAndroid
들어가보면 장(chapter)별로 동작가능한 안드로이드 프로젝트가 들어있습니다.
총 51개의 commit이 포함되어 있네요.
깃헙에 올려놓으면 좋은 것이 책이 출간된 후에도 코드를 업데이트할 수 있고 그것을 fork(가져간) 사람들은 변경사항을 적용하기 쉽다는 것입니다. 또한 코드가 잘못되면 pull request하여 독자가 수정을 요청할 수도 있습니다.
3. 본문과 예제 코드를 함께 만들기
대부분의 경우는 본 경우에 해당할 것 같습니다. 집필을 할 때 예제 코드가 미리 준비되어 있는 경우는 거의 없습니다. 목차를 만들고 그 안에 장과 절을 구성해나가고 그 안에 storyline을 따라가면서 자연스럽게 필요한 소스 코드를 만들게 됩니다.
책안에 포함되는 예제 코드는 실행가능성을 기준으로 다음과 같이 구분할 수 있습니다.
1) 실행가능한 프로젝트 (IDE 혹은 console에서 실행)
2) 독립 실행가능한 파일들 (.java , .python 등)
3) 실행가능한 코드의 일부분(code snippet)
4) 의사코드 (pseudocode)
앞서 살펴본 <그레이들 레시피>의 경우 장 별로 안드로이드 스튜디오의 프로젝트를 제공합니다.
한편 제가 집필한 <RxJava 프로그래밍>의 경우 java용 프로젝트와 Android 프로젝트 이렇게 두 개를 제공하고 장별 내용은 자바 패키지로 구별하고 있습니다.
링크: https://github.com/yudong80/reactivejava (java용)
링크: https://github.com/yudong80/reactivejava/tree/master/chapter06/rxAndroid (Android 용)
항상 실행가능한 코드만 제공할 수 있는 것은 아닙니다. 안드로이드 프로젝트의 경우 실행을 위해서는 java파일 뿐만 아니라 layout과 resource와 같은 XML 파일들도 필요하기 때문에 때로는 간결성을 위해 코드의 일부분만 제공하기도 합니다.
또한 <RxJava를 활용한 리액티브 프로그래밍>(인사이트, 2017)의 경우 제한된 내용에 많은 내용을 포함하기 위해 코드의 주요 로직만을 넣는 방식을 사용했습니다.
- 장점은 많은 내용을 압축적으로 전달할 수 있다는 점이었고
- 단점은 내용은 알겠는데 실제로 어떻게 동작하는지 추측만 할 뿐이어서 답답하게 느껴졌습니다.
마지막은 의사코드입니다. 이러한 경우는 특정언어에 종속되지 않는 내용을 전달하거나 알고리즘을 알려줄 때 사용합니다. 구체적인 실행은 언어마다 달라질 수 있거든요.
예를 들면 고전인 GoF의 <디자인패턴> 이나 <리팩터링> 같은 책이 그러한 분류입니다. 하도 오래전에 봐서 (책이 회사에 있어설..) 정확하게 확인은 못하겠지만 개념적으로 위의 책은 특정 언어와는 무관한 일반적인 프로그래밍 원리를 다루고 있기 때문에 굳이 코드의 "실행가능성"을 엄격하게 할 필요는 없는 것 같습니다.
4. 프로젝트로 예제 코드 구성하기
초기에 개념에 대한 책들이 나오면 그 다음에 이어지는 테마는 "활용"입니다. 활용에 가장 좋은 것은 구체적인 무언가.. 소위 프로젝트를 만들어 보는 것이죠.
제가 작년에 읽었던 책중 <안드로이드 프로그래밍>(제이펍, 2016) 은 그러한 원리를 보여주고 있습니다.
http://www.yes24.com/24/goods/28983198?scode=032&OzSrank=9
최종적인 프로젝트를 위해 mini 프로젝트를 기획하고 차근차근 일부분을 구성해갑니다.
사실 교육기관이 아닌 이상 집필을 이렇게 기획하는 것은 쉽지가 않습니다. 처음 집필하시는 분들은 이렇게 하는 것은 차후에 "준비가 되었을때" 시도해보시길 권장드립니다.
5. 평소에 코드를 만들자
제가 말씀드리고 싶은 내용을 한마디로 요약하면 "평소에 예제 코드를 만들자"입니다.
책을 쓰고 싶은 주제가 있다면 github에 repository를 만들고 책 내용을 너무 고려하지 말고 필요한 코드를 하나씩 모으거나 작성해보시는 것을 추천드립니다.
글의 내용을 "기획" -> "목차" -> "장/절" 로 하향식으로 구성하는 것도 중요하지만
반대로 필요한 코드 조작(snippet)을 모아 모아..혹은 개발 팁(tip)들을 모아서 상향식으로 내용을 구성하는 것도 완결성을 위해 필요합니다.
저는 <RxJava 프로그래밍>을 집필하면서 특정 기간 매일 매일 commit을 올리면서 책을 쓰는 것이라기 보다 예제를 만들고 그것의 설명을 붙여나가는 식으로 집필을 하기도 했습니다. 한가지 방식만 있는 것은 아니더라구요.
링크: https://github.com/yudong80/reactivejava/commits/master
매일매일 하는일이 코딩인 우리 개발자들에게 책쓰기 보다 자연스러운 것은 오히려
프로젝트를 열고 (github)
IDE에서 코드를 작성하고
동작하면 git에 올리고 (commit)
하는 일이기 때문입니다.
여러분이 집필 및 그 동기부여에 제 책쓰법(책쓰는 프로그래머가 되는 법)이 큰 도움이 되었으면 좋겠습니다.
감사합니다.
2018.1.22
