[Swift] 주석

[Swift] 주석

이 글은 Swift 프로그래밍 책을 읽고 요약한 내용입니다.

 

주석 : 프로그램 소스 코드에 정보를 남기는 목적으로 사용

주로 코드를 다시 봤을 때 필요한 중요 메모나 다른 프로그래머에게 설명하기 위한 메모 등을 주석으로 남김

 

Xcode의 퀵헬프 기능

• Xcode에는 말풍선의 형태로 레퍼런스 문서의 요약된 내용을 보여주는 퀵헬프 기능이 있음. 코드를 작성하는 중에 레퍼런스 문서로 이동하지 않고도 (퀵헬프를 지원하는) 데이터 타입이나 메서드 등의 간단한 정보를 확인할 수 있음

• 퀵헬프를 보려면 퀵헬프를 보기 원하는 항목(변수, 상수, 함수, 메서드, 타입 등) 위에 마우스 커서를 위치한 다음 키보드의 옵션(option) 키를 누른 상태로 클릭하면 됨. 또는 퀵헬프를 보기 원하는 항목에 커서를 위치한 다음 Quick Help Inspector(단축키 command + option + 2) 를 통해 퀵헬프를 확인할 수도 있음

• 마크업 문법에 맞춰 메서드나 변수, 클래스 등에 주석을 작성하면 퀵헬프로 다른 프로그래머가 해당 내용을 확인할 수 있음

 

주석 남기기

• 한 줄 주석 : 슬래시 두 개를 사용하여 나타냄

  // 한 줄 주석은 이렇게 표현

• 여러 줄 주석 : 슬래시와 별표를 사용하여 나타냄

  /* 여러 줄 주석을 시작할 때는 슬래시와 별표를 사용
  이 줄의 앞에 별다른 표기가 없지만 이 줄도 주석으로 인식
  주석을 긑내고 싶을 때는 별표를 먼저 쓰면 됨 */
  
  /*
  한 줄만 주석을 달아도 무방함
  */

• 중첩 주석 : 스위프트에서는 여러 줄 주석 안에 여러 줄 주석 또는 한 줄 주석을 넣는 중첩 주석을 지원함

  대부분의 프로그래밍 언어는 중첩 주석을 지원하지 않음

  /* 여러 줄 주석 안쪽에
  /* 추가로 여러 줄 주석을 포함할 수 있으며
  // 그 안에 한 줄 주석을 추가하여도 무방함
  */
  이 부분도 주석처리 됨
  */

 

마크업 문법을 활용한 문서화 주석

https://developer.apple.com/library/archive/documentation/Xcode/Reference/xcode_markup_formatting_ref/

Markup Formatting Reference: Markup Overview

• 한 줄 주석은 슬래시 세 개를 사용하고 여러 줄 주석은 별표 두개를 사용함
• 자동으로 문서화 주석 코드 조각을 생성하려면 문서로 만들려는 요소(상수, 변수, 함수 등)에 커서를 위치한 후 Xcode 메뉴의 [Editor] -> [Structure] -> [Add Documentations] (단축키 command + option + /) 을 선택함

/// 오류 타입의 열거형
/// - noName : 이름을 전달받지 못했을 때 발생하는 오류
/// - incorrectAge(age: Int) : 나이가 0세 미만, 150세 초과인 경우 잘못된 나이로 인식하여
/// 오류로 처리
/// - unknown : 알 수 없는 오류
enum HelloError: Error {
  case noName
  case incorrectAge(age: Int)
  case unknown
}

 

마크업 형식이 적용된 HelloError 열거형의 퀵헬프

 

/**
여기에 작성되는 텍스트는 Description 부분에 표기됨

텍스트 간에 한 줄을 비워 놓으면 줄바꿈이 됨

'-', '+', '*'를 사용하여 원형 글머리 기호를 사용할 수 있음

- 이렇게
+ 이렇게
* 이렇게

아니면 번호로 글머리 기호를 매겨줄 수도 있음

1. 1번
2. 2번
6. 3번

앞에 붙는 번호는 크게 중요하지 않음. 자동으로 번호를 매겨 줌
(밑에 이미지를 보면 6이 아니라 3으로 표기 된 것을 볼 수 있습니다.)

----
문단 바꿈

바를 세 개 이상 사용하면 긴 줄로 문단을 나눠줌

----

언더바 또는 별표를 사용하여 텍스트를 강조할 수 있음

텍스트를 기울이고 싶으면 *A pair of marks*를 사용하고

텍스트를 굵게 표기하고 싶으면 **Two pair of marks**를 사용하면 됨

관련 링크를 넣어줄 수도 있음

[jieun Blog](https://zeunny.tistory.com)

---
등호를 사용하면 바로 위 텍스트를 큰 제목으로 표시해줌. 텍스트 앞에 #을 하나 붙여줘도 동일한 효과를 냄

큰 제목 표시
===

바를 사용하면 바로 위 텍스트를 중간 크기 제목으로 표시해줌. 텍스트 앞에 #을 두 개 붙여줘도 동일한 효과를 냄

사용 예
---

다른 텍스트보다 네 칸 이상 들여쓰기하면 코드 블록을 만들어줌. 또한 강세표(backquote, `)를 세 개 이상 한 쌍으로 묶어도 코드 블록을 만들어줌

    // 코멘트를 넣어줄 수도 있음
    let myName: String = "jieun"
    try helloSwift(myName, yourAge: 100)

​````
let myName: String = "jieun"
try helloSwift(myName, yourAge: 100)
​````

Precondition, Postcondition, Requires, Invariant, Complexity, Important, Warning, Author, Authors, Copyright, Date, SeeAlso, Since, Version, Attention, Bug, Experiment, Note, Remark, ToDo 등의 키워드를 통해 적절한 정보 제공 가능
- note : 강조하고픈 메모를 노트로 남겨둘 수 있음
- author : 작성자를 남길 수 있음
- warning : 주의해야 할 점을 남길 수도 있음

---
> 매개변수와 반환 값 등도 적절히 표기해줄 수 있음
- parameters :
    - yourName : 당신의 이름
    - yourAge : 당신의 나이. 0 미만 또는 150을 초과하면 오류 발생
- Throws : 오류가 발생하면 HelloError의 한 케이스를 throw
- returns: Hello string
*/
func helloSwift(yourName: String?, yourAge age: Int = 0) throws -> String {

  guard let name: String = yourName else {
    throw HelloError.noName
  }

  if age > 150 {
    throw HelloError.incorrectAge(age: age)
  }

  return "Hello Swift!! My name is \(name)." + (age > 0 ? " I'm \(age) years old." : "")
}

 

마크업 형식이 적용된 HelloSwift() 함수의 퀵헬프

(이미지가 한 화면에 들어오지 않아 나눠서 캡쳐했습니다)