> ## Content Index
> Fetch the complete content index at: https://www.popit.kr/llms.txt
> Use this file to discover other available public pages before exploring further.

# [Rspec] 좋은 설명문 작성하기
- URL: https://www.popit.kr/rspec-writing-good-descriptions/
- Published: 2017-10-25T22:30:43.000Z
- Updated: 2017-10-26T00:10:17.000Z
- Author: 최 민석
- Tags: #소프트웨어, rsepc, 문서화

RSpec은 TDD의 문서화에 중점을 두고 개발된 훌륭한 BDD툴입니다. (BDD는 어플리케이션의 개발과정을 확인하는 사람이 읽을 수 있는 명세서를 적는 일을 말합니다.) 저의 경우 [Better Specs](http://www.betterspecs.org/ko/?ref=popit.kr)을 통해 좋은 테스트 스위트에 대해 알 수 있었지만 **좋은 설명문에 관해서는 한가지 오해가 있었습니다.** 이 글에서는 올바른 설명문에 관해 제가 했던 오해와 결론에 대해 간단히 공유하려고 합니다.

Rspec에 관한 좋은 테스트 스위트를 제시하고 있는 [Better Specs](http://www.betterspecs.org/ko/?ref=popit.kr#should)에는 아래와 같은 글이 있습니다.

> 테스트를 설명할때 should를 사용하지 마세요. 현제 시제의 3인칭 시점으로 작성합시다. 새로나온 expectation 를 사용하시면 더욱 좋습니다.

처음 읽었을때는 it블록 안에 should대신 expect를 사용해야 한다는 식으로 오해하고 말았습니다. 그런데 다시 한번 읽어 보니 **"현제 시제의 3인칭 시점으로 작성합시다."**라는 문장이 눈에 띄었습니다. 그동안 *제가 잘못된 이해로 작성하곤 했던 Example*은 아래와 같습니다.

```ruby
describe 'User' do
  describe '#updata_orders' do
    it '주문정보가 갱신됩니다' do
      ...
    end
  end
end
```

"주문정보가 갱신됩니다"는 그 자체로는 어색함이 없는 문장입니다. 그러나 문장 앞에 it이 있다는 사실을 생각해 보면 어색함이 느껴집니다. "주문정보가 갱신됩니다"를 it과 함께 표현하면 아래와 같은 문장이 됩니다.

> 그것은 주문정보가 갱신됩니다

올바른 문장은 "그것은 주문정보를 갱신합니다"이지 않을까요? 처음으로 돌아가서 "현제 시제의 3인칭 시점으로 작성합시다."에 따라 다시 작성한 Example은 아래와 같습니다.  

```ruby
describe 'User' do
  describe '#updata_orders' do
    it '주문정보를 갱신합니다' do
      ...
    end
  end
end
```

조금 더 자연스럽게 느껴지시나요? 별 차이가 없는 것 같나요? 사실 Example을 현제 시제의 3인칭 시점으로 작성으로 작성해야 하는 이유는 문법에 맞는 문장을 작성하기 위함만은 아닙니다. 더 중요한 이유는 **읽기 쉬운 문서화**에 있습니다.

Rspec을 통한 사람이 읽기 쉬운 문서화를 위해서는 describe와 it을 다음과 같이 정의하여야 합니다.

- describe: 설명하려고 하는 주체를 정의해야 하합니다. describe은 example group의 주어가 됩니다.
- it: it은 describe을 주어로 하는 설명문이야 합니다. 해당 문장의 it을 example group의 describe으로 교체해도 문장이 어색해지지 않아야 합니다.
  - X) 주문정보가 갱신됩니다. -> User#updata\_orders는 주문정보가 갱신됩니다.
  - O) 주문정보를 갱신합니다. -> User#updata\_orders는 주문정보를 갱신합니다.

위에서 예로 제시한 "잘못된 이해로 작성하곤 했던 Example"에서 "주문정보가 갱신됩니다"는 describe에서 제시된 "User#updata\_orders"가 아닌 "Oder(주문정보)"를 주어로 설명해 버렸습니다. 별거 아닌 거 같고 저 정도야 어떻게 쓰든 금방 이해할 수 있을 듯하지만, 저런 잘못된 설명문 하나하나가 모여 문서화된 TDD를 읽기 어렵게 만드는 건 아닐까요?

지금까지 살펴본 Rspec에서의 좋은 설명문에 대해 요약하자면 다음과 같습니다.

- it은 describe의 대상을 가리키는 대명사입니다.
- it에 들어가는 문장은 주어가 3인칭 단수인 현재시제의 문장을 사용해야 합니다.
- it에 들어가는 문장이 describe를 가리키기 어렵다면 다른 describe가 필요한지 고민해 볼 필요가 있습니다.
- it에 들어가는 문장은 영어로 작성하기를 권합니다. 그 이유는 영어로 작성하는 편이 it이 문장의 일부라는 사실을 의식하기 쉽기 때문입니다.