모든 분야에서 기본기의 중요성을 강조하는데 나 역시 그 생각에 동감한다. 프로그래머로서 가장 중요한 기본기 중 하나는 사용하는 프로그래밍 언어의 규칙과 방식을 정확하게 이해하고 따르는 것이라고 한다. 그래서 Swift의 공식 문서인 API Design Guidelines를 통해 기본기를 다지려고 한다. 먼저 Fundamentals 부분을 살펴볼 것이다. 정리보다는 요약 글
iOS 개발자는 꼭 알아야 할 기본 원칙들의 핵심 가이드라인에 대해 알아보자
사용 시점에서의 명확성이 가장 중요한 목표.
명확성은 간결성보다 더 중요.
모든 선언에 문서화 주석을 작성.
/// Returns a "view" of `self` containing the same elements in
/// reverse order.
/// 동일한 요소들을 포함하는 'self'의 'view'를 역순으로 변환.
func reversed() -> ReverseCollection
요약에 초점
가능하면 마침표로 끝내고 완전한 문장 사용 x
함수나 메서드가 무엇을 하는지, 무엇을 반환하는지 설명
/// Inserts `newHead` at the beginning of `self`.
mutating func prepend(_ newHead: Int)
/// Returns a `List` containing `head` followed by the elements
/// of `self`.
func prepending(_ head: Element) -> List
/// Removes and returns the first element of `self` if non-empty;
/// returns `nil` otherwise.
mutating func popFirst() -> Element?
완전한 문장을 사용하지 않는게 무엇일까?
: 너무 길거나 복잡한 문장보다는 간결하고 명확한 문장을 사용하라는 것.
❌ "이 함수는 사용자의 정보를 데이터베이스에서 가져와서 화면에 표시한다."
✅ "데이터베이스에서 사용자 정보 가져옴"
주석 작성시 지금까지는 슬래쉬 두 개('//')를 많이 사용했는데 예시에서는 세 개를 많이 사용한다. 어떤 차이가 있을까?
👉 한 줄 주석('//'): 코드의 특정 줄 또는 옆에 간단한 설명을 추가할 때, 코드 내부에서 잠시 어떤 부분을 비활성화 하거나, 해당 라인의 동작을 간략하게 설명할 때
👉 문서화 주석('///', '/...*/'): API문서화 가이드에 사용, 함수, 클래스, 구조체, 열거형 등의 선언 바로 위에 위치한다.
subscript가 어디에 접근하는지 설명
/// Accesses the 'index' th element
subscript(index: Int) -> Element { get set }
이니셜라이저가 무엇을 생성하는 지 설명
/// Creates an instance containing 'n' repetitions of 'x'.
init(count n: Int, repeatedElement x: Element)
모든 선언은 선언된 entity가 무엇인지 설명
/// A collection that supports equally efficient insertion/removal
/// at any position.
/// 어떤 위치에서든 동일하게 효울적인 삽입/삭제를 지원하는 컬렉션.
struct List {
/// The element at the beginning of 'self', or 'nil' if self is
/// empty.
/// 'self'의 시작 부분에 있는 요소, 'self'가 비었을 경우 'nil'.
var firtst: Element?
}
한 개 이상의 절과 글머리 기호로 이어갈 수 있다. 절은 빈줄로 구분, 완벽한 문장 사용
주석 내에서 여러 문단을 작성할 수 있으며, 문단 간에는 빈 줄로 구분한다.
각 문단은 완전한 문장으로 작성한다.
/// 각 `items`의 원소에 대한 텍스트 표현을 표준 출력에 작성한다. ← 요약
/// ← 빈 줄
/// 각 아이템 `x`에 대한 텍스트 표현은 `String(x)` 표현식에 의해 ← 추가 설명
/// 생성된다.
///
/// - Parameter separator: 아이템 사이에 출력될 텍스트. ⎫
/// - Parameter terminator: 마지막에 출력될 텍스트. ⎬ 매개변수 섹션
/// ㅣ ⎭
/// - Note: 마지막에 개행 없이 출력하려면 `terminator: ""`를 ⎫
/// 전달하세요. ⎟
/// ㅣ ⎬ 기호 명령
/// - SeeAlso: `CustomDebugStringConvertible`, ⎟
/// `CustomStringConvertible`, `debugPrint`. ⎭
public func print(
_ items: Any..., separator: String = " ", terminator: String = "\n")
정보를 제공할 때 글머리 기화와 심볼 명령 구문을 알고 사용해야 한다.
참고: Swift API Guidelines, yagom-academy