1주차 - HMHZ의 DocC 적용기

[PictureHouse]

안녕하세요! 3기 매크로팀 HMHZ의 라움입니다.

매크로를 시작한지도 어느덧 두 달이 되었고 대부분의 팀이 개발을 진행중일거라 생각됩니다.

그냥 개발을 진행하면 좋겠지만 아무래도 팀원들끼리 함께 개발을 해야하다보니 우리가 꼭 생각하면서 해야할 것이 있습니다. 바로 개발 협업이죠!

협업과 관련해 팀 HMHZ가 했던 고민과 시도들을 함께 보러 가보시죠!

---

매크로 팀 포밍이 되고 개발팀이 함께 자리에 앉아있습니다.

그런데 내 옆에 앉아있는 이 팀원들과 개발 협업을 한적이 있었던가…그러고 보니까 없네…

“이 사람은 어떻게 일하지?”

“이 사람은 어떻게 코드를 작성할까?”

“내가 이 사람이 작성한 코드를 알아볼 수 있을까?”

등등의 고민을 하다가 “아몰라 일단 개발 시작해!!”라는 생각을 가지고 개발을 시작하죠.

각자 개발할 부분도 나누고 열심히 작업을 합니다.

다른 사람이 미리 기능을 구현한 코드를 가지고 내가 맡은 뷰를 열심히 그리죠.

후… 드디어 끝!을 외치고 코드를 봤는데 아래와 같은 상황이 벌어졌습니다.

어라? 흠…뭔가 이상한데…? 그래도 일단 잘 서있네…?

지금 이게 무슨 상황이냐구요? 존윅을 만들려고 했는데 독윅이 만들어져있는 상황이랄까요.

피규어를 만든 제작자는 존윅과 그의 개를 만들어주길 바랬지만 우리는 개의 머리를 한 독윅과 존의 머리를 한 개를 만들어버렸어요.

팀원과 함께 개발을 진행하면서 다른 팀원이 작성한 코드를 사용해서 개발을 하다가 독윅의 경우처럼 의도와 다르게 코드가 작성되는 경우가 있을 수 있잖아요?

그래서 팀 HMHZ의 개발팀은 독윅이 아니라 제대로된 존윅을 만들기 위해 고민하기 시작했어요.

이때 뉴준성이 말했죠.

“우리 DocC를 사용해보죠?”

??? : “그게 뭔데. 왜 또 혼자만 아는거 말해요.”

네. 도란과 라움은 DocC를 처음 들어봤어요. 여기서 DocC가 뭔지 한번 알아보고 갑시다.

---

DocC?

코드에 구현 내용 등을 설명해주는 문서 주석을 작성하는 것이며 아래와 같은 효과를 얻을 수 있습니다.

• Quick Help를 통해 다른 소스파일에서 필요한 내용을 쉽게 확인할 수 있게 해줍니다.

• 협업 할 때 다른 사람의 코드 이해를 돕습니다.

DocC를 작성해봅시다.

한 문장씩 작성할 때는 아래와 같이 작성합니다.

/// comment

여러 문장을 작성할 때는 아래와 같이 작성합니다.

/**
comment
*/

클래스, 구조체, 열거형, 함수, 변수 등에 DocC를 작성할 수 있으며 코드 위에서 가장 가까운 문서 주석이 대상의 문서 주석으로 인식됩니다.

그리고 문서 주석은 키워드를 통해서 섹션을 나눌 수도 있습니다.

/// Summary
///
/// Discussion/Overview
///  
/// - Parameters:
///    - [param]: [description]
/// - Returns: [description]
/// - Warning: [description]
/// - Author: [name]
/// - Version: [version number]
/// - Note: [note message]
/// - Tip: [tip message]
/// - Todo: [todo message]

“대쉬(-) 키워드” 형식으로 작성하면 위와 같이 키워드를 구분해줍니다.

커스텀 키워드를 작성하고 싶다면 아래와 같이 작성해주면 됩니다.

/// > Keyword: description

Summary의 바로 밑부분인 Discussion에서는 마크다운을 이용해 내용을 작성할 수 있습니다.

/// **bold**
/// ~~cancle~~
/// _italic_
/// `keyword`
///
/// ```swift
/// code
/// ```
/// - dot
///
/// 1. one
/// 2. two
///
/// Table  | Description
/// --- | ---
/// `row1`| This is row1
/// `row2`| This is row2
///
/// \* escaping

문서 주석 단축키는 “option + cmd + /”이며 주석을 작성하고 싶은 대상에게 마우스를 놓고 단축키를 누르면 바로 윗부분에 문서 주석을 추가해줍니다.

---

??? : “DocC가 뭔지는 이제 알겠는데… 그래서 이걸 어떻게 써먹죠?”

DocC에 작성할 수 있는 내용과 키워드는 많은데 그냥 작성하면 결국에 중구난방 형식이 될 것 같았기에 저희는 DocC의 템플릿을 만들어보기로 했습니다.

어떤 상황에 어떤 키워드가 필요할 것인지에 대해서 토론을 나눈 끝에 아래와 같이 세 개의 DocC 템플릿을 만들었죠.

Type DocC

/// <#Summary#>
///
/// <#Discussion#>
///
/// - Note: <#이 함수가 싱글톤인지에 대한 여부 등을 작성하면 됩니다.#>
/// - Author: <#name#>

Attribute DocC

///

Function DocC

/// <#Summary#>
///
/// - Parameters:
///   - a: <#a description#>
///   - b: <#b description#>
///
/// <#Discussion#>
///
/// - Throws: <#description#>
/// - Returns: <#description#>
///
/// - Author: <#description#>

흠…이렇게 써놓고 보니까 Type DocC와 Function DocC에서 작성할 내용의 길이가 기네요. 이 내용들을 매번 기억해내면서 작성하는건 좀 아니잖습니까?
그래서 길이가 긴 DocC들은 Xcode의 스니펫으로 추가하기로 했습니다.

Xcode에서 작성한 DocC를 선택하고 우클릭을 해줍니다. 여기서 Create Code Snippet을 선택해서 저희가 작성한 DocC를 스니펫으로 추가합니다.

스니펫의 이름, 요약 등을 작성하고 하단에서 Language, Platform, Completion, Availability 선택까지 마친 후에 Done을 선택해주면 스니펫 등록이 완료됩니다!

스니펫으로 추가한 DocC가 잘 나오는군요!

---

이런 과정으로 DocC 사용을 하기로 결정하고 Xcode에 스니펫으로 추가하기까지의 과정을 거쳤습니다.

협업을 도와줄 DocC를 적극적으로 활용하면 개발을 진행했습니다.(사실 계속 진행중…)

지금까지 저희가 작성한 DocC 살짝 보고 가실게요!

DocC를 사용해서 코드에 대한 설명을 작성하니 다른 사람의 코드를 이해하는데 훨씬 편해진 것 같습니다!

여러분도 원활한 협업을 위해 DocC를 한번 사용해보시는건 어떨까요?

[yeniful]

우와~~~ 포럼에 DocC 글이 올라오다니 !!! 넘 좋구만요 !!!!! 👍🤓👍

[darongzzang]

우와~ '///'을 지금까진 함수명, 변수명을 알려주기 위해 간간히 사용해왔는데 이렇게 사용할수도 있군요?! 넘 유용해요!👍

[anjiniii]

많은 사람들과 함께 개발하면서 중요한 점이 문서화인 것 같아요!
그리고 미래의 나에게도 몇 몇 코드의 잘 정리된 글은 활용하기에도 도움이 되는 것 같아요.

코드를 문서화하기에 DocC가 아주 좋은 방법이겠군용!!!
그리고 스니펫으로 추가하는 것도 너무 좋아보여요 🐧✨