Dart 튜토리얼 16편: Effective Dart 요약(Style·Documentation·Usage·Design)

Why#

NOTE

타입 이름이 들쑥날쑥하면, 코드를 읽는 사람이 “이게 클래스인지/함수인지”부터 추측해야 합니다.
그래서 타입과 확장은 형태를 통일해두는 편이 좋습니다.

What#

NOTE

클래스/enum/typedef/타입 파라미터는 UpperCamelCase로 이름을 짓는 규칙이 제시됩니다.
확장(extension)도 같은 규칙을 따릅니다.

How#

TIP

타입 이름과 확장 이름 예시는 다음과 같이 제시됩니다.

1
class SliderMenu {
2
  // ...
3
}
4

5
class HttpRequest {
6
  // ...
7
}
8

9
typedef Predicate<T> = bool Function(T value);

1
extension MyFancyList<T> on List<T> {
2
  // ...
3
}
4

5
extension SmartIterable<T> on Iterable<T> {
6
  // ...
7
}

Watch out#

WARNING

이름이 바뀌면 사용처도 함께 바뀌므로, 공개 API에서는 네이밍을 특히 안정적으로 유지해야 합니다.
즉, “일단 대충 짓고 나중에 바꾸기”가 반복되면, 코드와 문서의 비용이 함께 커집니다.

결론: 타입/확장은 UpperCamelCase로 시작해, 형태부터 통일합니다.

Why#

NOTE

주석이 “문장 같지 않거나” 형식이 제각각이면, 읽는 사람이 내용을 신뢰하기 어려워집니다.
또한 공개 API가 문서화되지 않으면, 사용자가 올바르게 쓰기 어렵습니다.

What#

NOTE

일반 주석은 문장처럼 작성하는 팁이 제시됩니다.
그리고 공개 API를 문서화하려면 /// 형태의 문서 주석을 쓰는 규칙이 제시됩니다.
dart doc는 이 문서 주석을 읽어 API 문서를 생성합니다.

How#

TIP

문장 형태의 주석 예시는 다음과 같습니다.

1
// 이 위치 이전에 무언가가 오면 안 된다.
2
if (_chunks.isNotEmpty) return false;

문서 주석은 ///로 작성합니다.

1
/// 이 청크가 분리되지 않았을 때의 문자 개수.
2
int get length => ...;

Watch out#

WARNING

문서로 남길 목적의 설명을 블록 주석(/* ... */)로 쓰지 않는 규칙이 제시됩니다.
블록 주석은 “일시적으로 코드 조각을 주석 처리”할 때 사용하고, 그 외에는 //를 사용합니다.

결론: 주석은 문장처럼 쓰고, 공개 API는 /// 문서 주석으로 dart doc 흐름에 태웁니다.

Why#

NOTE

패키지의 내부 구현(lib/src)은 유지보수자가 “자유롭게 바꿀 수 있는 영역”으로 취급됩니다.
외부가 그 영역을 직접 import하면, 작은 버전 변화에도 코드가 깨질 수 있습니다.

What#

NOTE

다른 패키지의 lib/src 아래 라이브러리를 import하지 않는 규칙이 제시됩니다.
또한 package: import를 사용하면 디스크 경로에 덜 의존하게 되며, lib 경계를 넘나드는 상대 경로 import를 피하는 규칙이 제시됩니다.

How#

TIP

src 내부 import를 피하고, 공개된 경로(package:)로 import하는 습관을 들입니다.
또한 “같은 파일을 두 경로로 import”하는 상황을 만들지 않습니다.

1
import 'package:my_package/api.dart';
2
import '../lib/api.dart';

Watch out#

WARNING

서로 다른 import 경로는 Dart가 “서로 다른 라이브러리”로 인식할 수 있습니다.
그러면 타입이 같아 보여도 서로 다른 것으로 취급되는 등, 이해하기 어려운 오류로 이어질 수 있습니다.

결론: import는 package:를 기준으로 정리하고, src 구현 내부를 직접 import하지 않습니다.

Why#

NOTE

API를 쓰는 사람은 “내가 알고 있는 개념”에 기대어 코드를 이해합니다.
이때 용어가 흔들리거나 약어가 과하면, 학습 비용이 커집니다.

What#

NOTE

같은 개념에는 같은 이름을 쓰는(일관성) 기준이 제시되고, 불필요한 약어를 피하는 기준이 제시됩니다.
또한 사용 코드를 문장처럼 읽어보는 방식으로 이름을 점검하는 기준이 제시됩니다.

How#

TIP

일관성/문장처럼 읽히는 예시는 다음과 같이 제시됩니다.

1
pageCount         // 필드
2
updatePageCount() // pageCount와 일관됨
3
toSomething()     // Iterable의 toList() 관례와 일관됨
4
asSomething()     // List의 asMap() 관례와 일관됨

1
// "errors가 비어 있으면..."
2
if (errors.isEmpty) {
3
  // ...
4
}
5

6
// "구독(subscription)이여, 취소해."
7
subscription.cancel();

Watch out#

WARNING

용어를 바꾸는 리팩터링은 단순한 변수명 변경이 아니라, 사용자의 학습 모델을 바꾸는 작업이 됩니다.
그래서 공개 API는 초기에 용어를 안정적으로 정하고, 바꾸려면 근거와 마이그레이션 경로를 함께 준비해야 합니다.

결론: API는 “용어 일관성 + 문장처럼 읽히기”로 점검하면, 사용자가 더 빨리 이해할 수 있습니다.