주석

주석 (Comments)

코드를 읽는 사람에게 남기는 메모, 주석의 종류를 살펴봐요. Dart에는 한 줄 주석, 여러 줄 주석, 그리고 문서 주석이 있어요.

출처: Dart 공식 문서

본문

한 줄 주석 (Single-line comments)

한 줄 주석은 //로 시작해요. //부터 그 줄의 끝까지는 Dart 컴파일러가 무시해요.

void main() {
  // TODO: refactor into an AbstractLlamaGreetingFactory?
  print('Welcome to my Llama farm!');
}

여러 줄 주석 (Multi-line comments)

여러 줄 주석은 /*로 시작해서 */로 끝나요. /*와 */ 사이의 내용은 문서 주석이 아닌 한 컴파일러가 무시해요. 여러 줄 주석은 중첩(nest)도 가능해요.

void main() {
  /*
   * This is a lot of work. Consider raising chickens.

  Llama larry = Llama();
  larry.feed();
  larry.exercise();
  larry.clean();
   */
}

문서 주석 (Documentation comments)

문서 주석은 ///나 /**로 시작하는 한 줄 또는 여러 줄 주석이에요. 연속된 줄에 ///를 쓰는 것도 여러 줄 문서 주석과 같은 효과를 내요.

문서 주석 안에서는 대괄호로 감싼 내용만 analyzer가 해석해요. 대괄호를 이용하면 클래스, 메서드, 필드, 최상위 변수, 함수, 매개변수를 가리킬 수 있어요. 대괄호 안에 쓰인 이름은 해당 문서화된 프로그램 요소의 어휘적 유효 범위(lexical scope)에서 해석돼요.

다른 클래스나 인자(argument)를 참조하는 문서 주석 예시를 볼게요.

/// A domesticated South American camelid (Lama glama).
///
/// Andean cultures have used llamas as meat and pack
/// animals since pre-Hispanic times.
///
/// Just like any other animal, llamas need to eat,
/// so don't forget to [feed] them some [Food].
class Llama {
  String? name;

  /// Feeds your llama [food].
  ///
  /// The typical llama eats one bale of hay per week.
  void feed(Food food) {
    // ...
  }

  /// Exercises your llama with an [activity] for
  /// [timeLimit] minutes.
  void exercise(Activity activity, int timeLimit) {
    // ...
  }
}

이 클래스의 생성된 문서에서는 [feed]가 feed 메서드 문서로 가는 링크가 되고, [Food]는 Food 클래스 문서로 가는 링크가 돼요.

Dart 코드를 해석해서 HTML 문서를 만들고 싶다면 Dart의 문서 생성 도구인 dart doc을 쓰면 돼요. 생성된 문서의 예시는 Dart API documentation에서 볼 수 있고요, 주석을 어떻게 구성하는 게 좋을지에 대한 조언은 Effective Dart: Documentation에서 확인할 수 있어요.

더 알아보기 (Learn more)