문서 주석 지침
문서 주석 지침 (Doc Comment Guidance)
문서 주석은 어디에 다느냐만큼 무엇을 쓰느냐도 중요해요. Zig가 문법적으로 강제하는 건 아니지만, 주석이 실제로 도움이 되도록 지키면 좋은 기준이 몇 가지 있어요. 어떤 정보를 남기고 어떤 걸 버려야 하는지, 위험한 조건은 어떻게 표현하는지 이 지침이 정리해 줘요.
본문
Zig 가이드가 권장하는 문서 주석 작성 기준은 네 가지예요.
- 문서화하는 대상의 이름에서 이미 충분히 짐작되는 정보는 생략해요. 함수 이름이 이미 하는 일을 말해 주는데 같은 내용을 주석으로 다시 적을 필요는 없어요.
- 비슷한 여러 함수에 같은 정보를 중복해서 적는 건 오히려 권장돼요. 중복이 IDE나 다른 도구들이 더 나은 도움말을 보여주도록 도와주거든요.
- 위반하면 확인되지 않는(unchecked) Illegal Behavior를 일으키는 불변 조건을 나타낼 때는 assume이라는 단어를 사용해요.
- 위반하면 안전 검사되는(safety-checked) Illegal Behavior를 일으키는 불변 조건을 나타낼 때는 assert라는 단어를 사용해요.
핵심을 짚어 보면, assume과 assert 둘 다 불변 조건을 나타내는 단어인데 그 차이는 검사 방식이에요. assume은 검사가 켜져 있지 않아서 위반해도 컴파일러가 잡지 못하고, assert는 안전 검사가 적용되어 위반하면 런타임에 잡혀요. 그래서 문서를 읽는 사람이 "이 조건이 깨지면 어떻게 되는 거지?"를 헷갈리지 않도록, 이 두 단어를 상황에 맞게 구분해서 쓰면 돼요.
더 알아보기
- Comments: 문서 주석(
///)과 top-level doc comment(//!)의 종류와 위치 - Illegal Behavior:
assume/assert가 가리키는 불변 조건 위반의 의미