파이썬에서 함수에 대한 주석(Docstring)을 작성하던 도중에, 보다 보편적인 주석 양식을 참고하여 습관을 들이면 좋을듯 하여 구글의 ‘파이썬 스타일 가이드’를 참고해보았다.
왜 구글 스타일 가이드일까?
일단, 설명을 해보자면 구글에서 ‘파이썬’은 인터프리터 언어(구글에서는 ‘다이나믹 언어’라는 용어를 사용하더라) 중에는 ‘메인 언어’이다. 구글 내에서 파이썬을 사용하는 사람들이 많고, 파이썬 코드를 함께 읽고(review) 의사 소통 해야 하는 경우가 많다. 구글이란 단체의 규모 역시 큰 규모의 단체인 만큼 자신들이 유지하는 ‘스타일 가이드’ 역시 ‘보편성’을 추구하려는 쪽을 택한다.
하지만 (파이썬) 개발자들 중에는 자신만의 코드 습관이 있을 것이고, 자신에게 그러한 코드 습관이 생긴 이유도 있을 것이다(보통은 해당 언어의 특징 내지 개발 환경으로부터 기인한다). 때문에 가이드에 기재된 지시사항이 본인에게 납득이 가지 않을 경우, 스타일 가이드를 거부하려 할 수도 있다.
이러한 점을 구글도 잘 알고 있는지, 스타일 가이드를 기재하면서 해당 사항들에 대한 ‘장점(pros)’과 ‘단점(cons)’를 명시하고 있다. 간단하고도 실재적인 설명이 파이썬 커뮤니티의 스타일 가이드 보다 더 실용적인(practical) 측면에 이해하기가 쉬워, 구글 스타일 가이드를 기준으로 삼아보았다.
스타일 가이드 모두를 한 줄씩 살펴보면서 나의 것으로 소화 하면 그만큼 유익도 많을테지만, 우선 나에게 관심 사항은 주석, 그 중에서도 docstring(함수나 클래스에 대한 설명란. 함수나 클래스 명 다음 줄에 기재하며, 홑따옴표 세 개’’’ 또는 겹따옴표 세 개 “””로 열고 닫는다)에 있으므로 해당 사항에 대해서만 보았다.
그럼 우선, 함수 독스트링에 대하여 보자. 구글 스타일 가이드에서는 함수, 메소드, 제너레이터를 모두 ‘함수’로 묶어서 부른다.
함수 독스트링(docstring) 작성 기준
A function must have a docstring, unless it meets all of the following criteria:
* not externally visible
* very short
* obvious
구글은 ‘모든 함수’에게 독스트링을 작성하라고 하지는 않는다. 하지만, 이 세 개의 조건 중 하나라도 벗어난다면 반드시 독스트링을 작성하라고 한다.
외부로 노출되지 않는 함수(not externally visible)
예를 들어 ‘모듈’을 작성할 경우, 해당 메소드나 함수가 그 모듈을 이용하는 사람(client)에게 제공되지 않는 경우를 말한다. 이용자에게 노출되지 않는 ‘은닉’된 함수라는 조건이다. 다른말로, ‘이용자’에게 일단 해당 함수가 제공이 되는 경우 독스트링을 무조건 작성해야 한다.
매우 짧은 함수(very short)
함수 중에는 짧지만 반복되는 몇 개의 줄을 함수로 묶는 경우도 있다. 그러니까, 코드를 보기에 짧지 않다면 독스트링을 작성해야 한다.
‘짧은 코드’에 대한 기준이 명시되어있으면 더 좋을듯 한데, 명시되어있지 않기 때문에 이는 개발자들마다 상대적인 측면이 있지 않을까 싶다. 혹 다른 스타일 가이드에서 ‘짧은 코드’에 대한 기준에 대해 언급하는 부분이 있다면 좋을텐데, 이와 관련해서는 구글에서 작성한 ‘코드’를 구문분석 해보면 보다 더 확실할듯 하다.
명시적인 함수(obvious)
명시적인 것에 대하여는 ‘두 가지 부분’이 있을 것이다. 하나는 ‘함수 명’이 명시적이어야 할 것이고, 다른 하나는 ‘작성된 코드’가 명시적이어야 할 것이다. 위에서 말하는 ‘명시적인’이란 표현에는 이 두 가지가 모두 다 해당되어야 할 것이다.
위의 세 가지 조건을 토대로 본다면, 함수에서 ‘독스트링’을 작성하지 않으려면 모듈이나 클래스의 이용자에게 은닉된 함수 중 매우 짧고 명시적이여만 독스트링을 건너 뛸 수 있다. 이 세 가지가 모두 충족되지 않는다면, 독스트링을 작성해야 할 것이다.
스타일 가이드의 ‘독스트링 작성’ 조건만 살피더라도, 독스트링 작성이 귀찮은 개발자는 할 수만 있으면 ‘짧은 코드’를 사용하여 코드를 ‘명시적’으로 적으려고 할 것이다. 이것만 가지고서도 개발자에게 ‘간단하며 명시적인 코드’를 작성하도록 유도를 하고 있다.
그럼 독스트링 작성에 대하여는 어떤 내용이 들어갈까? 다음의 설명을 보자.
A docstring should give enough information to write a call to the function without reading the function’s code. The docstring should describe the function’s calling syntax and its semantics, but generally not its implementation details, unless those details are relevant to how the function is to be used.
독스트링은, 함수 내 코드를 읽지 않고도 함수를 사용할 수 있는데 필요한 충분한 정보를 제공해야 한다고 설명한다. 여기에는 함수의 호출 문법(syntax and its semantics)이 포함된다. 그리고 함수를 사용하는데 알아야 할 정보가 아닌 이상, 함수 내부 구현을 자세히 설명할 필요는 없다.
What a specification may talk about
A specification of a method can talk about the parameters and return value of the method, but it should never talk about local variables of the method or private fields of the method’s class. You should consider the implementation invisible to the reader of the spec.
해당 글에서 명세(Specification)에 대한 설명은 독스트링에 무엇을 적어야 하는지를 말한다. 내부 구현은 명세(독스트링)에 적지 말라고 한다. MIT는 명세를 어떻게 작성해야 하는지 프로그래밍에 대한 기초 수업에서부터(MIT 6.00.1) 가르친다. 그러니까, 독스트링을 작성하는 것은 ‘소프트웨어 작성’의 일부인 것이다.
그런데 여기서 MIT의 ‘소프트웨어 구축’ 수업과 ‘구글 독스트링 스타일 가이드’에 차이가 있다. MIT 소프트웨어 구축 수업은 ‘자바’를 기반으로 하여, 개발자(메소드 이용자)가 해당 메소드의 코드를 ‘볼 수 없는’ 환경에서 구현을 하는 경우를 전제한다. 반면에 구글은, 해당 메소드를 이용하는 사람이 아니더라도 짧지 않거나, 명시적이지 않은 코드에 모두 ‘독스트링’을 작성해달라 하고 있다.
구글은 왜 ‘내부 코드’에도 독스트링을 작성하라고 할까?
내가 작성한 코드를 추후 다른 사람이 수정하게 될 수도 있다
당연한 이야기이겠지만, 해당 코드 작성자가 퇴사를 하였을 경우 후임이 와서 그 코드를 유지보수 해야 하는 상황이 생길 수 있다. 후임 개발자는 당연히 전임 개발자가 작성한 코드에 필요한 부분을 덧붙이며 수정 작업을 할 것이고, 이 과정에서 전임 개발자가 작성한 ‘함수’를 이용하는 입장이 될 것이다. 여기에서 ‘함수의 이용자’는 후임 개발자가 될 수 있는 것이다.
하지만, 필자는 독스트링을 작성하는 이유가 비단 ‘함수를 이용하는 사람’에 머물지는 않는다고 생각을 한다. 여기에 그동안 MIT 수업을 살피고, 또 구글 스타일 가이드 대로 독스트링을 작성하며 필자가 가지게 된 생각을 더해보겠다.
독스트링을 작성하는 것은 ‘함수를 구축(construction)’하는 과정에 포함된다
필자가 구글 스타일 가이드 대로 독스트링을 작성하며 알게된 것은, 독스트링을 작성할 때 해당 함수의 ‘목적’이 보다 더 구체화된다는 것이다. 때때로 함수를 작성하다 보면, 기존에 작성된 함수를 충분히 검토해볼 시간이 모자랄 때가 있다. 이러한 경우 함수의 코드를 열어볼 기회 없이 단순히 ‘함수명’만으로 추론을 할 수 밖에 없고, 작성을 하다 보면 기존에 다른 함수에 들어간 기능과 겹치는 경우가 생길 수 있다.
반면에 함수 작성 과정에서 ‘독스트링 작성’을 포함하게 되면, 이 함수의 ‘목적’이 무엇이고 이 함수를 ‘어떻게 사용할지’에 대한 여부를 함께 고민하며 독스트링에 적어놓는다. 머릿 속에서 한번 그 목적과 용례가 ‘구체화’ 되었기 때문에, 함수간 ‘용도’와 ‘목적’을 구분하는데 있어 훨씬 도움이 된다. 구현은 둘째 치고, 이 함수에 앞으로 포함될 ‘코드의 범위’를 미리 고민할 수 있기 때문에 추후 코드를 ‘기존의 함수’에 덧붙일지, ‘새로운 함수를 추가할지’ 여부를 판단하기가 쉬워지는 것이다. 그만큼 각각 ‘함수’의 코드 응집력도 좋아질수 밖에 없다.
필자의 이러한 경험을 미루어보면, 개발에 있어 ‘독스트링 작성’은 개발의 ‘일부’이다. 독스트링을 작성하는 것은 내가 앞으로 사용할 이 함수의 ‘목적’과 ‘용도’를 정하는 것이고, 이를 통하여 보다 더 정교하고 조직적인 소프트웨어의 구축이 가능해진다.
그런데 아직 한국 프로그래밍의 교육 과정은 코드의 ‘기능 구현’에만 집중되어 있는듯 하진 않나 싶다. 개발 문화 역시 ‘자신이 쓸 함수’에는 굳이 독스트링을 작성하지 않아도 된다는 생각이 강한듯 하다. 좋은 코드 작성 습관은 ‘코드 꿈나무’ 때부터 알려주어, 좋은 개발자로 향하는 지름길로 인도해야 하지 않나 싶다.
