2011.07.29

기고 | 클라우드에서의 문서화 작업법

David Taber | CIO
코드에 주석을 달지 않거나 시스템을 문서화(documenting)하지 않은 것에는 변명의 여지가 없다. 이런 관행이 테스트 개발에 있어 비용절감과 품질에 있어 도움이 된다고 하더라도 그렇다. 하지만 사실을 직시하자. 시스템 문서화는 필요악이 아니다. 게다가 관리가 불가능한 코드의 보안 처리라는 지저분한 작업을 안겨주지도 않는다.

불행히도 클라우드에서의 작업은 개발자들에게  "퍼블릭 클라우드 서비스라 액세스도 통제도 불가능하지 않습니까? 문서 작업을 할 수 있는 부분이 없습니다"라는 새로운 구실을 제공할 수 있다.

좋다. 개발자들의 변명에 이런 식으로 반박해 보자.

'퍼블릭이든 프라이빗이든 클라우드 서비스를 이용하는 모든 소비자들은 서비스가 하는 일과 활용방법, (버그와 오류 조건을 포함) 소비 측면 활용과 결정 요소 측면에서의 행동들을 문서화 작업해야 한다.'

그러면 아마 "우리가 사용하는 모든 모듈의 동일한 클라우드 서비스를 대상으로 문서화 작업을 해야 한다는 이야기 아닙니까?''라고 볼멘 소리를 할게 분명하다. 이 경우 '문서화 정보를 개발 및 통합 팀 전체가 액세스할 수 있는 위키(Wiki)와 구글 독스(Google Docs), 또는 다른 협업 시스템에 집어 넣어야 한다'라고 대답해야 한다.

이는 모든 사람들이 외부 인터페이스와 모듈 및 서비스 의존성에 있어 베스트 프랙티스를 이행하도록 견인하는 역할을 한다. 개발팀 일원 전부에 의해 생성되고 관리되는 콘텐츠를 보유한 중앙화된 보관소인 것이다.

개인적인 경험에 비춰보자면 데이터 딕셔너리와 개체-관계 모델, 비즈니스-프로세스 설명, 또는 인터페이스 문서화를 책임진 중앙형 팀을 갖는 것의 대안이 생산해 낼 수 있는 것은 단 2가지뿐이다. 문서화를 하지 않는데 따른 구실이거나 기껏해야 구식 또는 부정확한데다 양만 많은 부분들 뿐이다.

그렇다면 모듈 인터널이나 변수의 어드미니스트리비아(Administrivia)를 문서화하기에 위키가 최적의 장소일까? 나쁜 생각은 아니다. 그러나 개발자들은 대부분의 시간을 문서 영역에서 보내지 않게 될 것이다. 오히려 앱 내부의 변수를 조정하거나 코드를 해킹하게 된다.

코드 작업을 할 때, 인라인 주석달기(commenting)을 장려할 수 없다. 측정을 해야만 한다. 개발한 코드에 있어, 우리는 시스템에 대해 여타 모듈을 점검하는 것을 허락하지 않는다. 최소 라인의 10%가 주석이고, 또 다른 10%는 인라인 리마크(remarks)를 갖고 있는 게 아니라면 말이다.

인라인 코드 요건은 테스트 모듈에서는 두 배로 뛰어 오른다. 어떤 특정 라우팅을 대상으로 테스팅을 해야 하는지, 테스트 과정에서 실패가 있을 때 모듈의 어디를 살펴봐야 하는지 추측이 어려울 수 있기 때문이다.

사용하고 있는 코드 통합 시스템이 이를 대비한 대응 및 실행 메카니즘을 갖고 있을 수도 있다. 하지만 그렇지 못하다면 일반적으로는 스크립트 작업을 해야 한다.

일부 클라우드 앱과 프레임워크에는, 본질적으로 주석을 지원하지 않는 스크립팅과 워크플로우, 포뮬러 언어가 있다. 그러나 문서화 메시지(예, IF 0=1, "The comment goes here -- maybe as long as 80 characters")를 포함하고 있으며 이용할 수 없는 코드 단편을 통해 주석을 심을 수 있는 방법이 상시 존재한다.

따라서 코드 주석을 달지 않은데 대한 변명을 없앨 수 있다. 비록 액션의 대부분이 코드에 있지는 않지만, 현대의 클라우드 기반 애플리케이션은 선언형(Declarative) 프로그래밍이고 맞춤형 필드/객체/관계이다.

또 문서를 측정해야 한다. 개발자와 관리자 모두에게 인센티브가 되어야 한다. 세일즈포스닷컴(Salesforce.com) 같은 시스템에서는, 모든 새 필드에 셀프 문서화를 위한 2번의 기회가 주어진다.

디스크립션(Description) 영역과 헬프-버블(Help-Bubble) 정보 영역이다. 필자는 각각에 다른 정보를 넣는 방식으로 둘 모두를 활용할 것을 권장한다.

클라우드 시스템에 이런 기능이 없다면, 실제 필드가 따라붙는 이름을 가진 가짜 필드를 활용하고, 사람이 읽을 수 있도록 메타데이터 정보를 추가한다.  

예를 들어, 'salestem'이라는 숫자 필드에 '♦salesteam'이라는 문자 필드를 더한 후, 디폴트 값을 디스크립티브(descriptive) 문자로 설정할 수 있다. 시스템이 필드 이름에서 확장 ASCII를 지원하지 않는다면 '{'나 '¡' 같은 구두점을 마무리로 사용한다. 시스템이 문자 필드에 디폴트 값을 지원하지 않는다면, 할 수 있는 한 현명하게 가짜 필드 이름으로 임베드를 해야 한다.

모듈 사이를 오가는 메시지를 대상으로 한 셀프 문서화는 어떨까? WSDL이나 다른 XML에서는 XLM은 물론 지원 DTD에 많은 메타데이터를 집어 넣을 수 있다. 시스템 대응 시간이 늦을 수 있지만, 많은 노력과 시간은 아니다.

코드에서 직접 클라우드를 호출할 때, REST나 SOAP 메시지를 기반으로 한 라이브러리를 네트워크에서 완벽히 통제하기란 어렵다. 이 경우, 추가 정보만을 담은 문자 변수나 아웃바운드 요청에서의 둘을 보내는 것만으로 문제해결이 가능할 것이다. 또 장기적으로 학습곡선이 쉬워진다.

핵심은 이렇다. 클라우드가 여타의 문서화 이행을 강제하지 않는다 하더라도, 클라우드 앱 기능과 웹 서비스 프로토콜을 이용해 시스템의 셀프 문서화 역량을 한층 강화할 좋은 방법이 있다는 것이다. 다음 클라우드 프로젝트에서는 실행에 옮겨보기 바란다.

* David Taber는 ‘세일즈포스닷컴 성공의 비밀’의 저자이며 세일즈포스닷컴 관련 컨설팅 기업인 세일즈로지스틱스의 CEO다.  ciokr@idg.co.kr



2011.07.29

기고 | 클라우드에서의 문서화 작업법

David Taber | CIO
코드에 주석을 달지 않거나 시스템을 문서화(documenting)하지 않은 것에는 변명의 여지가 없다. 이런 관행이 테스트 개발에 있어 비용절감과 품질에 있어 도움이 된다고 하더라도 그렇다. 하지만 사실을 직시하자. 시스템 문서화는 필요악이 아니다. 게다가 관리가 불가능한 코드의 보안 처리라는 지저분한 작업을 안겨주지도 않는다.

불행히도 클라우드에서의 작업은 개발자들에게  "퍼블릭 클라우드 서비스라 액세스도 통제도 불가능하지 않습니까? 문서 작업을 할 수 있는 부분이 없습니다"라는 새로운 구실을 제공할 수 있다.

좋다. 개발자들의 변명에 이런 식으로 반박해 보자.

'퍼블릭이든 프라이빗이든 클라우드 서비스를 이용하는 모든 소비자들은 서비스가 하는 일과 활용방법, (버그와 오류 조건을 포함) 소비 측면 활용과 결정 요소 측면에서의 행동들을 문서화 작업해야 한다.'

그러면 아마 "우리가 사용하는 모든 모듈의 동일한 클라우드 서비스를 대상으로 문서화 작업을 해야 한다는 이야기 아닙니까?''라고 볼멘 소리를 할게 분명하다. 이 경우 '문서화 정보를 개발 및 통합 팀 전체가 액세스할 수 있는 위키(Wiki)와 구글 독스(Google Docs), 또는 다른 협업 시스템에 집어 넣어야 한다'라고 대답해야 한다.

이는 모든 사람들이 외부 인터페이스와 모듈 및 서비스 의존성에 있어 베스트 프랙티스를 이행하도록 견인하는 역할을 한다. 개발팀 일원 전부에 의해 생성되고 관리되는 콘텐츠를 보유한 중앙화된 보관소인 것이다.

개인적인 경험에 비춰보자면 데이터 딕셔너리와 개체-관계 모델, 비즈니스-프로세스 설명, 또는 인터페이스 문서화를 책임진 중앙형 팀을 갖는 것의 대안이 생산해 낼 수 있는 것은 단 2가지뿐이다. 문서화를 하지 않는데 따른 구실이거나 기껏해야 구식 또는 부정확한데다 양만 많은 부분들 뿐이다.

그렇다면 모듈 인터널이나 변수의 어드미니스트리비아(Administrivia)를 문서화하기에 위키가 최적의 장소일까? 나쁜 생각은 아니다. 그러나 개발자들은 대부분의 시간을 문서 영역에서 보내지 않게 될 것이다. 오히려 앱 내부의 변수를 조정하거나 코드를 해킹하게 된다.

코드 작업을 할 때, 인라인 주석달기(commenting)을 장려할 수 없다. 측정을 해야만 한다. 개발한 코드에 있어, 우리는 시스템에 대해 여타 모듈을 점검하는 것을 허락하지 않는다. 최소 라인의 10%가 주석이고, 또 다른 10%는 인라인 리마크(remarks)를 갖고 있는 게 아니라면 말이다.

인라인 코드 요건은 테스트 모듈에서는 두 배로 뛰어 오른다. 어떤 특정 라우팅을 대상으로 테스팅을 해야 하는지, 테스트 과정에서 실패가 있을 때 모듈의 어디를 살펴봐야 하는지 추측이 어려울 수 있기 때문이다.

사용하고 있는 코드 통합 시스템이 이를 대비한 대응 및 실행 메카니즘을 갖고 있을 수도 있다. 하지만 그렇지 못하다면 일반적으로는 스크립트 작업을 해야 한다.

일부 클라우드 앱과 프레임워크에는, 본질적으로 주석을 지원하지 않는 스크립팅과 워크플로우, 포뮬러 언어가 있다. 그러나 문서화 메시지(예, IF 0=1, "The comment goes here -- maybe as long as 80 characters")를 포함하고 있으며 이용할 수 없는 코드 단편을 통해 주석을 심을 수 있는 방법이 상시 존재한다.

따라서 코드 주석을 달지 않은데 대한 변명을 없앨 수 있다. 비록 액션의 대부분이 코드에 있지는 않지만, 현대의 클라우드 기반 애플리케이션은 선언형(Declarative) 프로그래밍이고 맞춤형 필드/객체/관계이다.

또 문서를 측정해야 한다. 개발자와 관리자 모두에게 인센티브가 되어야 한다. 세일즈포스닷컴(Salesforce.com) 같은 시스템에서는, 모든 새 필드에 셀프 문서화를 위한 2번의 기회가 주어진다.

디스크립션(Description) 영역과 헬프-버블(Help-Bubble) 정보 영역이다. 필자는 각각에 다른 정보를 넣는 방식으로 둘 모두를 활용할 것을 권장한다.

클라우드 시스템에 이런 기능이 없다면, 실제 필드가 따라붙는 이름을 가진 가짜 필드를 활용하고, 사람이 읽을 수 있도록 메타데이터 정보를 추가한다.  

예를 들어, 'salestem'이라는 숫자 필드에 '♦salesteam'이라는 문자 필드를 더한 후, 디폴트 값을 디스크립티브(descriptive) 문자로 설정할 수 있다. 시스템이 필드 이름에서 확장 ASCII를 지원하지 않는다면 '{'나 '¡' 같은 구두점을 마무리로 사용한다. 시스템이 문자 필드에 디폴트 값을 지원하지 않는다면, 할 수 있는 한 현명하게 가짜 필드 이름으로 임베드를 해야 한다.

모듈 사이를 오가는 메시지를 대상으로 한 셀프 문서화는 어떨까? WSDL이나 다른 XML에서는 XLM은 물론 지원 DTD에 많은 메타데이터를 집어 넣을 수 있다. 시스템 대응 시간이 늦을 수 있지만, 많은 노력과 시간은 아니다.

코드에서 직접 클라우드를 호출할 때, REST나 SOAP 메시지를 기반으로 한 라이브러리를 네트워크에서 완벽히 통제하기란 어렵다. 이 경우, 추가 정보만을 담은 문자 변수나 아웃바운드 요청에서의 둘을 보내는 것만으로 문제해결이 가능할 것이다. 또 장기적으로 학습곡선이 쉬워진다.

핵심은 이렇다. 클라우드가 여타의 문서화 이행을 강제하지 않는다 하더라도, 클라우드 앱 기능과 웹 서비스 프로토콜을 이용해 시스템의 셀프 문서화 역량을 한층 강화할 좋은 방법이 있다는 것이다. 다음 클라우드 프로젝트에서는 실행에 옮겨보기 바란다.

* David Taber는 ‘세일즈포스닷컴 성공의 비밀’의 저자이며 세일즈포스닷컴 관련 컨설팅 기업인 세일즈로지스틱스의 CEO다.  ciokr@idg.co.kr

X