Dart 튜토리얼 32편: 자동 수정과 포맷(dart fix·dart format·dart doc)

Why#

NOTE

분석기가 “고칠 수 있는 문제”까지 사람이 손으로 고치면 시간 낭비가 됩니다.
자동 수정이 가능한 항목은 도구에 맡기는 편이 안전합니다.

What#

NOTE

dart fix는 분석 이슈 중 자동 수정이 있는 항목과, SDK 업데이트 과정에서의 오래된 API 사용을 찾아 자동으로 수정합니다.

How#

TIP

먼저 변경 내용을 미리보기로 확인합니다.

1
$ dart fix --dry-run

그리고 적용합니다.

1
$ dart fix --apply

Watch out#

WARNING

자동 수정은 “분석기가 문제로 인식한 항목”에만 적용됩니다.
즉, 린트 규칙이 꺼져 있으면 수정 후보가 줄어들 수 있다는 흐름이 제시됩니다.
필요하면 analysis_options.yaml⁴에서 규칙을 활성화해 적용 범위를 늘릴 수 있습니다.

결론: dart fix를 먼저 실행하면, 반복적인 개선을 빠르게 정리하고 사람이 볼 부분을 줄일 수 있습니다.

Why#

NOTE

포맷이 흔들리면 코드 리뷰가 로직이 아니라 “공백/줄바꿈” 논쟁으로 흐르기 쉽습니다.
포맷은 도구로 고정하는 편이 좋습니다.

What#

NOTE

dart format은 포맷을 일관되게 맞추며, 기본적으로 파일을 덮어씁니다.
또한 출력 모드를 바꿔 “어떤 파일이 바뀌는지”만 확인할 수도 있습니다.

How#

TIP

전체 프로젝트를 포맷합니다.

1
$ dart format .

CI에서 “포맷 변경이 있는지”만 확인하려면 -o none과 --set-exit-if-changed를 조합합니다.

1
$ dart format -o none --set-exit-if-changed bin/my_app.dart

포맷 결과를 화면에 보여주려면 -o show를 사용합니다.

1
$ dart format -o show bin/my_app.dart

Watch out#

WARNING

기본 페이지 폭은 80이며, 프로젝트 단위로 바꾸려면 analysis_options.yaml의 formatter.page_width를 설정하는 방식이 제시됩니다.
또한 파일 단위로는 // dart format width=123 같은 마커를 파일 상단에 둘 수 있습니다.

결론: 포맷은 dart format으로 고정하고, CI에서는 “변경 발생 여부”를 exit code로 관리합니다.

Why#

NOTE

패키지나 라이브러리를 만들면, 사용자가 API를 이해할 수 있는 안내 자료가 필요합니다.
또한 문서 생성 과정에서 주석/구성 문제를 조기에 발견할 수 있습니다.

What#

NOTE

dart doc은 Dart 소스에서 HTML API 문서를 생성합니다.
생성 전에는 dart pub get과 dart analyze가 오류 없이 통과해야 한다는 조건이 제시됩니다.

How#

TIP

프로젝트 루트에서 문서를 생성합니다.

1
$ dart pub get
2
$ dart doc .

문서 문제만 검사하고 결과를 저장하지 않으려면 --dry-run을 사용합니다.

1
$ dart doc --dry-run .

Watch out#

WARNING

생성된 문서는 파일 시스템에서 직접 열기보다, HTTP 서버로 서빙해야 검색/사이드바 같은 기능이 정상 동작할 수 있다는 안내가 있습니다.
예시로 package:dhttpd를 전역 활성화해 doc/api를 서빙하는 흐름이 제시됩니다.

1
$ dart pub global activate dhttpd
2
$ dart pub global run dhttpd --path doc/api

결론: dart doc은 “문서 생성 + 문서 품질 검사” 역할을 같이 하므로, 릴리즈 전에 --dry-run까지 포함해 점검하는 편이 안전합니다.