서론
클라이언트 개발을 하다보면 여러가지 커스텀 뷰들을 만들게 된다. 그리고 좀 노련한 디자이너와 함께 일을 하다보면 여러 UI 컴포넌트들을 공통화시켜 재사용이 될 수 있도록 디자인하고 개발자는 그에 맞게 공통 컴포넌트를 개발해서 재사용을 하게 된다.
프로젝트 내 코드들의 문서화 작업을 하다보니 로직과 관련된 부분은 주석을 잘 달아서 문서화하기에 충분하지만 UI는 어떻게 하면 좋을까 고민을 하기 시작했다. UI는 시각적인 요소다보니 주석으로는 불충분하고 더욱이 Storyboard, XIB 등을 이용하여 공통화 작업을 하기에는 관리적인 요소도 애매하지만 뷰의 속성을 바꾸면서 확인하다보면 변경사항을 취소해줘야 하며, 해당 뷰에 대한 코드를 작성하는 것도 번거롭다.
개인적으로는 이러한 점 때문에 커스텀 뷰도 code기반으로 작성을 하는데 유일한(?) 단점이라면 코드만 보고 해당 뷰를 상상하기가 쉽지 않다는 것이다.
효율적인 문서화 작업
마침 프로젝트에 여유가 있어 미뤄두었던 소스 코드 문서화 작업을 하다가 UI 문서화를 좀 세련되고 효율적으로 해보고 싶다는 생각에 사로잡혔다. 앞에서도 얘기했지만 현재 담당하고 있는 프로젝트에서 뷰들은 모두 코드 기반이어서 이 단점을 없애고 싶었다.
앱 개발 시 공통 컴포넌트를 고르면 그 뷰의 모양을 바로 볼 수 있고 속성도 쉽게 변화시켜볼 수 있도록 하면 어떨까라는 상상에 빠졌다.
플레이그라운드에서 코드 불러오기
현재 프로젝트는 Cocoapods 때문에 Workspace로 관리되고 있다.
Documentations.playgrounds 파일을 Workspace 내에 만들어 보았다. 여기에 해당 뷰들을 어떻게 가져올 수 있을까 살펴보니 동일한 workspace 내에 playgrounds 파일이 존재하더라도 해당 코드를 바로 불러올 수는 없었다.
플레이그라운드에 대상이 되는 뷰를 불러오기 위해서는 import 를 통해 문서화를 할 대상들이 모인 모듈을 불러와야했다. 그렇다면 공통 컴포넌트들을 모듈화하는게 우선이었다.
모듈화하기 가장 쉬운 방법은 별도의 저장소(Repository) 를 만들어 거기에 공통 컴포넌트 클래스들을 모아놓고 SPM(Swift Package Manager)이나 Cocoapods 등을 이용하여 불러오는 방법이다.
이렇게 하면 공통 컴포넌트 추가, 변경, 삭제 시 해당 저장소에서 코드를 수정을 하고 릴리즈를 해야하는 번거로운 절차 예상되었다. 이미 공통 컴포넌트가 디자인 시스템으로 잘 구성되어 있다면 당연히 이렇게 하는게 가장 좋은 방법이겠지만 아직은 그럴 정도로 컴포넌트들이 성숙화되지 않았기에 다른 방법을 찾아야했다.
요구사항 다시 정리
Xcode Workspace 를 아래의 요구사항이 충족될 수 있게 재구성을 해야했다.
- 별도의 저장소를 이용하여 분리하기에는 공통 컴포넌트들의 성숙도가 낮다. 즉, 수정이 필요하면 언제든 수정을 해야한다. 하지만 성숙도가 어느 정도 올랐을 때는 언제든 분리가 가능해야 한다.
- 플레이그라운드를 이용하여 마크다운으로 문서화한다. 그리고 플레이그라운드 장점인 해당 뷰의 모습을 바로 볼 수 있고 또 뷰의 속성 변경 시 미리보기가 되어야 한다.
코드 파일들의 재구성
우선 공통 컴포넌트에 해당하는 파일들을 별도의 프로젝트에 담아야 했다. 워크스페이스에서 Framework 를 위한 프로젝트를 추가하고 이 프로젝트의 이름을 CommonUI로 명명했다.
그 다음으로 아까 만든 Documentations.playground 파일을 이 프로젝트로 이동을 시켰다. 아래 스크린샷 처럼 workspace 내에 CommonUI 프로젝트가 위치하게 되었다.
빌드 실패
비지니스를 담당하고 있는 프로젝트(앱 본체)의 configurations를 기본 형태인 Debug / Release 로 쓰지 않고 이름을 변경했거나 다양한 환경을 추가하여 사용하는 경우 framework 를 찾을 수 없다는 오류가 나며 빌드가 되지 않는다.
이 경우에는 번거롭더라도 새로 추가한 CommonUI 프로젝트의 configurations 도 동일하게 맞춰줘야 한다. (유일한 단점이다..) 이 부분 때문에 삽질을 많이 했다…
플레이그라운드에서 테스트
다음은 플레이그라운드에서 CommonUI 프로젝트에 포함된 코드들을 사용할 수 있는지 테스트할 차례다.
BaseView 로 명명된 클래스를 CommonUI 프로젝트로 옮기고 BaseView 클래스 내 프로퍼티와 메소드 중 외부에서 호출이 필요한 부분에 접근자를 public 으로 변경해줬다.
import UIKit
open class BaseView: UIView {
public override init(frame: CGRect) {
super.init(frame: frame)
configure()
}
public required init?(coder aDecoder: NSCoder) {
super.init(coder: aDecoder)
configure()
}
open func configure() { }
open func bind() { }
}이 부분에서 Xcode 문제인지 바로 되진 않았고 Xcode 상단 스킴을 CommonUI 로 선택해 빌드를 한 번 해줘야했다.
다시 플레이그라운드 파일로 돌아와서 BaseView 의 인스턴스를 아래와 같이 생성하고 배경색을 바꿔줘봤다.
각 단계별로 미리보기도 첨부를 할 수 있어서 너무나 만족스럽다.
UIViewController 기반 클래스는 PlaygroundSupport 를 임포팅하여 플레이그라운드에서 미리보기를 할 수 있다.
https://www.hackingwithswift.com/example-code/uikit/how-to-create-live-playgrounds-in-xcode
문서 작성
이제 남은 것은 코드를 기반으로 문서를 작성하는 것이다. 앞서 만든 Documentations.playground 파일을 선택하고 마우스 오른쪽 버튼을 눌러 옵션을 호출하여 New Playground Page 를 선택하면 Documentations.playground 하위에 페이지가 만들어진다.
앞서 언급한 것처럼 플레이그라운드 내에서는 markdown 사용이 가능하다. 허용되는 문법은 아래 링크에서 확인할 수 있으며, 대부분의 markdown 태그가 사용 가능하다.
https://developer.apple.com/library/archive/documentation/Xcode/Reference/xcode_markup_formatting_ref/MarkupFunctionality.html#//apple_ref/doc/uid/TP40016497-CH54-SW1
http://www.thomashanning.com/xcode-markup-for-playgrounds/
markdown으로 작성된 문서는 아래 두 스크린샷처럼 렌더링 된 모습과 안된 모습으로 변경이 가능한데 Xcode 메뉴 내 Editor 하단에서 Show Rendered Markup / Show Raw Markup 을 선택하거나 오른쪽 정보 창에서 Render Documentation 체크 박스로 선택으로도 가능하다.
정리
이렇게 위에서 정리한 요구사항에 맞출 수 있는 환경을 구축하였다. Configurations 매칭이 안되서 framework 를 찾을 수 없다는 빌드 오류 때문에 삽질을 좀 하긴 했지만 비교적 쉽게 문서화를 위한 환경을 구축한 것 같다.
참고
