2007년 1월 24일 Google TechTalks에서의 Joshua Bloch의 강연입니다.
How To Design A Good API and Why it Matters (Slides)
InfoQ에서 공개되어 있는 Javapolis에서의 2005년 강연도 있습니다만, 내용은 같아 보입니다. Slides로 충분하다고 생각하지만 OOPSLA 2006에 제출하기 위해 만든 요약도 참고하세요.
Joshua Bloch에 대해서는 Effective Java에 관한 글에서 소개한 적이 있지만, 굳이 여기서 다시 언급할 필요도 없다고 생각합니다. Java의 주요 클래스 라이브러리들의 설계를 주도하여, Java의 API 설계 품질의 기준을 한층 끌어올린 그는, API 설계에 관해 전문가라고 해도 충분하다고 생각합니다.
이 강연의 주제는 제목 그대로 좋은 API를 설계하는 방법과 그 중요성에 대한 강연이고, 제가 아는 한 API 설계에 관한 대부분의 중요한 생각들을 담고 있다고 생각합니다. 그 생각들을 전달하는 면에 있어서도 매우 훌륭한 강연이기에 만약 아직 이 강연을 보신 적이 없으신 분들은 시간을 들여 직접 보실 가치가 있으리라고 생각합니다. 이 글에서는 주로 API의 설계 과정에 대한 내용에 대해 제가 현재 시점에서 인상적인 부분들에 대한 의견을 적어봅니다.
If you program, you are an API designer
예전에는 프로그래머들을 API 설계 경험이 있는 프로그래머와 그렇지 않은 프로그래머로 분류할 수 있다고 생각했습니다. API 설계를 하기 전에는 다른 프로그래머가 어떤 도메인에 대해서 어떤 생각을 가지고 있을지, 주어진 API를 사용할 때 얼마나 실수할 수 있을지, 주어진 API가 얼마나 이해하기 쉬울지에 대해서 고민해보지 않았으니까요. 그리고, 그러한 고민들을 통해서 문제들을 해결하는 방법을 깨닫는 과정이 중요하다고 생각했습니다. API 설계를 경험하고나서 제가 느낀 것은 학부 시절에 Automata 수업을 들었을 때의 느낌이었죠.
그런데, Joshua Bloch은 모든 프로그래머는 API 디자이너라고 얘기합니다. 이 말을 듣고 다시 생각해보니, 실제로는 모든 프로그래머는 자신이 만든 코드를 사용할 모든 사용자 – 즉, 최종 사용자 (end-user)이거나 다른 프로그래머들을 고려하지 않으면 안된다는 것을 깨달았습니다. 어쩌면 그만큼 프로그래머에 대한 잣대가 올라갔다는 생각도 듭니다.
Start with Short Spec–1 Page is Ideal
API 설계의 시작 단계에서는 기민성(agility)이 완전성( completeness)보다 중요하다는 이야기입니다. API 설계의 시작 단계에서는 실제로 그 API를 들고 사용자에게 부딪혀보지 않으면 그 API가 요구사항에 적합한지 알 수 없는데, 이해하기도 힘든 복잡한 API 스펙을 가지고는 사용자들이 이해하기도 힘들고, 변경하기도 힘들다는 것입니다. 일반적인 소프트웨어 개발은 기민성을 중요시하면서도 API 설계에 있어서는 기민성과 완전성 사이에서 저울질 하기가 어려운 면이 있었는데, 한 페이지라는 기준은 매우 훌륭한 기준인 것 같습니다. 그리고, 이 한 페이지를 들고 사용자와 부딪혀보는 과정들 (이를테면, Hallway testing) 도 매우 중요하게 여겨집니다.
When in doubt leave it out
API의 어떤 요소 (메서드, 파라미터, …)가 들어가야 할지 말기 고민된다면, 빼버리라는 것입니다. 이미 다른 사람들이 사용하는 API는 없애기 힘들지만, 추가하기는 쉬운 API의 특성에 기인하는 매우 중요한 특성입니다. 요구사항을 다른 부서 등과 조율하는 과정에서 애매모호한 기능 요구사항들이 항상 나타나는데 이에 대한 명확한 결정을 내리는 것이 가장 좋긴 하겠지만, 그렇지 못하는 경우도 흔히 벌어지는 일인 것 같습니다. 이 때, API의 이러한 특성은 요구사항의 결정에서도 중요한 근거가 될 수 있지 않을까 하는 생각이 드네요.
Write to Your API Early and Often
API 설계에서 가장 흔하게 겪고, 또 가장 중요한 문제점으로 드러나는 것은, API를 이용한 구현하는 도중에 특정 기능을 충족할 수 없음을 발견하는 것일겁니다. 기민한 개발 과정으로 볼 수도 있겠지만, API 사용자 입장에서는 부족한 API 설계 상의 문제를 파악하거나 API가 동작하지 않는 문제를 발견하는 것, 그리고 변경된 API를 적용하는 과정들은 매우 힘들고 비용이 많이 들 뿐만 아니라 괴로운 과정입니다. 이러한 문제들의 대부분은 결국 API를 이용해서 구체적인 프로그램을 만들어보는 것 밖에는 방법이 없고, 기본적으로 이 역할을 API 설계자에게 있어야 합니다. TDD를 한번이라도 해보신 분들은 아시겠지만, API를 사용하는 코드를 먼저 써보는 것은 API 설계에 커다란 도움이 됩니다. 그리고 이러한 과정에서 만들어진 API 예제를 사용자에게 제공하는 것은 API를 사용하는 방법을 쉽게 익힐 수 있도록 도와줄 뿐만 아니라 API 사용자들이 잘못된 사용 방법에 빠지지 않도록 도와줍니다. Joshua는 API 설계 시의 API 예제가 API를 사용하는 모든 코드 중에 가장 중요한 코드라고 얘기합니다. 이는 절대 과장이 아니라고 생각합니다. API 예제가 제공되지 않는 API를 직접 개발하거나 사용해본 입장에서 이 부분이 뼈저리게 느껴지는군요.
Document Religiously
API라고 한다면 가장 좋은 문서화가 요구되어야 하는 것은 당연한 것 같습니다. 하지만, 문서가 없는 API를 종종 봅니다. 저도 잘못된 내용의 문서화가 된 API를 쓰거나, 모든 측면의 문서화를 하지 않은 등의 실수들이 떠오릅니다. 문서화에는 정말 ‘Religiously’라는 단어 – 우리말로 굳이 옮긴다면 ‘열광적으로’ 라고 해야할까요 – 를 써야할 정도로 개발자가 그만큼 공을 들이지 않으면 안되는 것 같습니다.
Closing
이 강연은 비록 5년 전의 내용이지만, API의 설계 과정 뿐만 아니라, 일반적인 API 설계 원리, 클래스, 메서드, 익셉션의 설계에 관한 내용들을 담고 있으므로, 현재는 물론 앞으로도 계속 곱씹을 수 있는 내용이라고 생각합니다. 다시금 말씀드리지만, 한번씩은 보시기를 권해드립니다. 가능하다면, 누군가가 자막 번역을 해준다면 좋겠다는 생각이 드는군요.
제게는 API 설계에 대해서 예전에 했던 생각들을 더올리게 되면서 현재 직면하고 있는 문제들에 대해서도 새롭게 많은 고민들을 할 수 있게 해주는 강연이었습니다. 좋은 강연에 대해서 Joshua Bloch에게 감사드립니다.