[iOS - swift] Clean Code(클린 코드) - 4. 주석

되로록이면 주석을 지양

• 잘 달린 주석은 그 어떤 정보보다 유용하지만, 프로그래밍 언어 자체의 표현력이 풍부하다면 주석이 거의 필요하지 않을 것이므로, 주석이 필요 없도록 프로그래밍의 표현력에 집중
• 코드는 분리되어 점점 변하지만 주석을 직접 수정해주지 않으면 남아있는 경우가 존재
• 주석은 나쁜 코드를 보완하지 못하므로, "모듈의 이해를 위해서 주석을 달아야지" 보다는 "코드를 정리해야지"의 관점이 필요

WRONG

- 나쁜 코드를 보완하려는 목적으로 주석이 사용되었지만, 나쁜 코드를 정리하는 것이 훨씬 중요

// 직원에게 복지 혜택을 받을 자격이 있는지 검사
if ((employee.flags & HOURLY_FLAG) && (employee.age > 65)) { ... }

RIGHT

- 나쁜 코드를 정리하고 주석을 삭제

- 보기에도 훨씬 간결하고 가독성있는 코드

if (employee.isEligibleForFullBenefits()) { ... }

좋은 주석

주석을 사용하여 이해를 도울 수 있지만, 그래도 명심해야 하는 것은 정말 좋은 주석은 주석을 달지 않을 방법을 찾아낸 것

• 정보를 제공하는 주석 - 함수 이름을 변경하여 주석 삭제

WRONG

// 테스트 중인 Responder 인스턴스 반환
func responderInstance() -> Responder

RIGHT

- 나쁜 코드를 정리하고 주석을 삭제

func responderBeingTestedInstance() -> Responder

• 정규 표현식을 표현한 주석 - 해당 주석은 코드를 변경하여 보완할 수 없으므로 주석을 사용

// kk:mm:ss EEE, MMM dd, yyyy 형식
let timeMatcher = Pattenrn.compile("\\d*:\\d*: ...")

(좋은 주석) 다른 개발자에게 알리는 주석

• 특정 테스트 케이스를 실행할때 시간이 많이 걸리므로 그에대한 경고 메시지를 주석으로 남기는 형태

// 여유 시간이 충분하지 않다면 실행하지 마십시오.
func testWithReallyBigFile() {
  writeLineToFile(1000000000)
  ...
}

(좋은 주석) 중요성 강조

• 자칫 대수롭지 않다고 여겨질 뭔가의 중요성을 강조하기 위해서도 주석을 사용

let listItemContent = match.group(3).trim()
// 여기서 teim은 정말 중요하다. 문자열에 시작 공백이 있으면 다른 문자열로 인식되기 때문이다.
...

(나쁜 주석) 닫는 괄호에 다는 주석

• 함수의 목적대로 작고 캡슐화가 잘 된 함수에서는 불필요한 잡음 역할밖에 안하므로 주의

WRONG

try {
  while a <= b {
    ...
  } // while
} // try
catch {
  ...
} // catch

RIGHT

try {
  while a <= b {
    ...
  }
}
catch {
  ...
}

(나쁜 주석) 주석으로 처리한 코드

• 주석으로 처리된 코드는 다른 사람들이 지우기를 주저하며, 이런 코드들이 부채가되어 점점 커지는 점이 존재하므로 주석처리된 코드를 아예 만들지 말것

WRONG

weatherService.request(by: coord, sucessed: { (weather, forecast) in
    self.weather = weather
//    self.forecast = forecast
//    responceCounter += 1
//    self.isStartActive.accept(responceCounter > 1)
}) { error in
    print(error.localizedDescription)
}

RIGHT

weatherService.request(by: coord, sucessed: { (weather, forecast) in
    self.weather = weather
}) { error in
    print(error.localizedDescription)
}

* 참고: Clean Code (로버트 C. 마틴)