Swift GuideLines - 4.Naming

 

정리하면 이렇다.

1. 보편적인 단어를 써라

2. 사용자가 사용할 때 예상하지 못할 것 같은게 있으면 주석으로 작성을 해라 O(n^2)복잡도 같은것.

3. 클래스 내에서 동일한 이름으로 함수를 작성 할 때는 동일한 기능을 작성해라

4. 클래스 내에서 동일한 이름인데 반환값이 다른 짓은 하지 말아라

5. 주석을 작성 했을 때 유창하게 읽히게 파라미터 이름을 구성해라

 

Term of Art (아는 사람만 아는것)

• noun - a word or phrase that has a precise, specialized meaning within a particular field or profession. 명사 - 특정 필드나 전문영역에서 정확하고 특별함을 갖는 단어나 구절.
  • 일반적인 단어가 의미를 더 잘 전달한다면 잘 알려져 있지 않은 용어를 사용하지마세요.
    • “skin”으로 의도를 드러낼 수 있다면 “epidermis”를 쓰지 마세요. 전문용어는 필수적인 대화 수단이지만, 사용하지 않으면 제대로 전달되지 않을 때만 사용해야 합니다.
    • 전문용어를 사용할 땐 확립된 의미를 사용하세요.
    • → 전문가가 당연히 아는 용도로, 초급자가 검색 했을 때 나오는 의미로
  • 약어(줄임말, abbreviations)을 피하세요. 정형화 되어 있지 않은 약어를 이해하려면, 다시 풀어서 해석해야하기 때문에 전문 용어 라고 볼 수 있다.
  • 관례를 따르세요.
    • 기존 문화와 다른 용어를 사용하면서까지 초심자를 배려하지 마세요.
    • 보편적으로 사용된 프로그래머가 친숙한 용어를 사용해라
      • List(x) Array(o)
      • sin() (0)

⇒ 한마디로 이해하기 쉽고 보편적인 단어로 만들고, 검색했을 때 명확한 의미가 나오는 걸로 이름짓자.

---

General Conventions

• computed property의 복잡도가 O(1)이 아니라면 복잡도를 주석으로 남겨주세요.
  • 사람들은 보통 property에 접근할 때 엄청난 계산을 할거라고 생각하지 않습니다. 가정이 위배될 때 경고를 해주세요.

  import Foundation
  
  class Company {
  
  	/// Time Complexity: O(n^2)
  	var numberOfEmployes: Int {
  		var result: Int = 0
  		
  		(0...n).forEach {
  			(0...n).forEach { 
  					(0...n).forEach { 
  						result += 1	
  					}
  			}
  		}
  	}
  
  }
  

• 전역함수 대신에 method와 property를 사용하세요
  • 전역 함수는 특수한 경우에만 사용됩니다.
  1. 명확한 self가 없는 경우
  2. min(x, y, z)
  3. function이 generic으로 제약조건이 걸려있지 않을 때
  4. print(x)
  5. function 구문이 해당 도메인의 표기번인 경우 (대중적으로 사용되는 용어일때)
  6. sin(x)
• 대소문자 컨벤션을 따르세요
• type, protocol의 이름은 UpperCamelCase로, 나머지는 lowerCamelCase를 따릅니다.

---

기본 뜻이 같거나 서로 구별되는 도메인에서 작동하는 Method는 base name을 동일하게 사용 할 수 있습니다.

Good

기본적으로 같은 동작을 하기 때문에 같은 이름을 사용하는 것이 권장됩니다.

extension Shape {
	// Returns 'true' iff 'other' is within the area of 'self'.
	func contains(_ other: Point) -> Bool { ... }

  // Returns 'true' iff 'other' is entirely within the area of 'self'.
	func contains(_ other: Shape) -> Bool { ... }

  /// Returns 'true' iff 'other' is within the area of 'self'.
	func contains(_ other: LineSegment) -> Bool { ... }

}

e.g)

struct Shape {
    
    func contains(_ other: Point) -> Bool {
        
    }
    
    func contains(_ other: Shape) -> Bool {
        
    }
}

let shape = Shape()
shape.contains(Point())
shape.contains(Shape())

Bad

이름은 갖지만 하나는 index검색, 하나는 n번째에 해당하는 row를 가져오는 의미를 갖고 있음.

extension Database {
	// Rebuilds the database's search index
	func index() { ... }

	// Returns the 'n'th row in the given table
	func index(_ n: Int, inTable: TableID) -> TableRow { ... }

}

overloading on return type은 타입 추론 유무에 따라 모호한 경우가 있어서 권장되지 않습니다.

extension Box {

  /// Returns the 'Int' stored in 'self', inf any, and 
  /// 'nil' otherwise
	func value() -> Int? { ... }

  /// Returns the 'String' stored in 'self', inf any, and 
  /// 'nil' otherwise
  func value() -> String? { ... }
}

import Foundation
// Bad
struct Box {
    private let rawValue: Int
    
    init(_ rawValue: Int) {
        self.rawValue = rawValue
    }
    
    func value() -> Int? {
        rawValue
    }
    
    func value() -> String? {
        "\\(rawValue)"
    }
    
}

let myBox = Box(100)

// 사용하는데 불편함.
myBox.value() as Int?
myBox.value() as String?

---

주석을 읽기 쉽게 만들어주는 파라미터 이름을 선택하세요.

• 파라미터 이름은 function이나 method를 사용하는 곳에서 보이지 않지만, function이나 method를 설명해주는 역할을 갖습니다.
• func move(from start: Point) start가 설명해주는 역할을 갖게됨
• 유창하게 읽을 수 있게 작성하세요와 비슷한 규칙이다.

Good

이런 이름들은 주석을 읽기 쉽게 해줍니다.

/// Return an 'Array' containing the elements of 'self'
/// that satisfy 'predicate'
func filter(_ predicate: (Element) -> Bool) -> [Generator.Element]

/// Replace the given 'subRange' of elements with 'newElements'.
mutating func replaceRange(_ subRange: Range, with newElements: [E])

Bad

/// Return an 'Array' containing the elements of 'self'
/// that satisfy 'includedInResult' => 읽기가 안됨. 말이 이상해짐
func filter(_ includedInResult: (Element) -> Bool ) -> [Generator.Element]

/// Replace the range of elements indicated by 'r' with => r??이란게 뭐임? 이렇게됨
/// the contents of 'with'
mutating fun replaceRange(_ r:Range, with [E])