# 주석과 포맷팅

### 주석

#### 주석이란?

* 코드의 가독성을 위해 작성하는 설명글이다.
* 주석은 코드로 인식되지 않기 때문에, 가독성을 위한 목표로 사용한다.
* 모든 내용을 주석으로 넣으면, 코드가 지저분해질 수 있다.
  * 대부분 적절한 Naming을 사용하면, 해결가능하다.
  * 네이밍으로 표현할 수 없는 영역을 주석으로 표현해야한다.

#### 주석을 사용하는 상황

1. 법적인 정보를 담을 때

   ```swift
   // Copyright (C) 2021 ...
   ```
2. 코드의 의도를 명확하게 설명할 때

   ```swift
   // throughput을 늘리기 위해 스레드를 늘린다.
   for index in 0..<10 {
       // code 
   }
   ```
3. 중요성을 강조할 때

   ```swift
   // 최종 결제 전 진행해야하는 validation 함수
   func validateBuyable(wallet: Int, price: Int) {
       // code
   }
   ```
4. 결과를 경고할 때

   함수가 런타임에서 오류를 뱉을 수 있을 때, 함수 사용 시 주의가 필요할 때 등

   ```swift
   // WARNING: API 서버가 항상 양호한지 알 수 없다.
   func connectAPIServer() {
       // code
   }
   ```

***

#### **관용적으로 사용되는 키워드**

* `TODO` : 당장은 아니지만 다음에 해야 할 때 (골뱅이로 책임자를 작성하기도 한다.)
* `FIXME` : 치명적인 에러를 발생하는 코드는 아니지만 수정해야 할 때 (시간이 없어서 나중에 고칠게)
* `XXX` : 더 생각해볼 필요가 있을 때

```swift
// TODO@jiwon: 객체의 책임 분리하기
class Store {

    // FIXME: depth 줄이기
    func sellFood() {
        for food in foods {
            for discount in dicounts {
            // code
            }
        }
    }
}
```

***

### **포맷팅**

#### **Vertical Formatting**

* 하나의 파일에 모든 코드를 넣지 않고, 개념에 맞게 파일을 나누어 관리한다.

  * 파일을 보고 내용을 예측할 수 있다.

  ```swift
  // as-is

  // Store.swift
  class FruitsStore { }
  class ComputerStore { }

  // to-be

  // FruitsStore.swift
  class FruitsStore { }

  // ComputerStore.swift
  class ComputerStore { }
  ```
* 비슷한 개념의 코드는 붙이고, 다른 개념의 코드는 Spacing으로 분리한다.

  ```swift
  func testUserBuyProduct() -> Bool {
      var user = User()                 // data 정의
      var product = Product()
                                      // **spacing 분리**
      product.setSoldOut(true)          // 실제 로직 처리
      user.get(product)

      return true                       // 처리 결과 출력
  }
  ```

#### **Horizontal Formatting**

* 한 줄에 코드를 다 넣기보단 변수 등을 활용해서 가독성 높이기

  ```swift
  // as-is
  productList += [Product("모니터"), Product("키보드"), Product("노트북")]

  // to-be
  let items = Product("모니터"), Product("키보드"), Product("노트북")
  productList += items
  ```
* 너무 긴 네이밍은 지양하기

  ```swift
  // as-is
  let userWithNameAndEmail = User("지원", "zest1923@gmail.com")

  // to-be
  let user = User("지원", "zest1923@gmail.com")
  ```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://sois-organization.gitbook.io/today-i-learned/clean-code/02..md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.