파이썬 소스 코드 주석을 표준화하는 방법: Action Comment 표준 라이브러리 이해하기

이 글은 파이썬 생태계에서 사용되는 다양한 소스 코드 주석(comment) 문제를 해결하기 위해 제안된 하나의 표준 라이브러리에 대해 설명합니다.
여러 정적 분석 도구들이 각기 다른 형식의 특수 주석을 사용하면서 발생하는 혼란과 비효율을 짚어보고, 이를 해결하기 위해 등장한 Action Comment 표준 언어와 파서 라이브러리의 개념, 배경, 문법 구조, 그리고 활용 방식을 정리합니다. 파이썬 코드 분석 도구를 사용하는 개발자나, 이러한 도구를 직접 만드는 분들에게 특히 도움이 될 내용입니다.

반응형

---

파이썬 생태계에서 주석이 가지는 의미

파이썬에는 Ruff, Black, Mypy, Coverage, Isort, Bandit 등 다양한 소스 코드 분석 도구가 존재합니다.
이 도구들은 단순한 설명용 주석이 아닌, 동작을 제어하는 특수 주석을 사용합니다.

예를 들면 다음과 같습니다.

• Ruff, Vulture: # noqa, # noqa: E741, F841
• Black, Ruff: # fmt: on, # fmt: off
• Mypy: # type: ignore, # type: ignore[error-code]
• Coverage: # pragma: no cover
• Isort: # isort: skip
• Bandit: # nosec

이처럼 형식은 비슷해 보이지만, 표준은 존재하지 않습니다.
각 도구는 주석을 해석하는 방식도 제각각이며, 정규식부터 문자열 처리, 심지어 자체 파서까지 사용합니다.

---

기존 방식의 문제점

이러한 환경에서는 여러 문제가 발생합니다.

1. 사용자 관점의 문제
   • 도구마다 다른 주석 규칙을 외워야 합니다.
   • 한 줄에 여러 도구용 주석을 동시에 쓰는 것이 보장되지 않습니다.
2. 도구 개발자 관점의 문제
   • “주석 하나 읽기”라는 단순한 작업이 실제로는 매우 복잡합니다.
   • 잘못된 파싱, 예외 처리, 확장성 문제 등 실수가 발생하기 쉽습니다.

이 라이브러리는 바로 이 지점을 해결하기 위해 만들어졌습니다.

---

Action Comment 표준 라이브러리란?

이 라이브러리는 소스 코드용 액션 주석(Action Comment) 에 대한
단순하고 직관적인 표준을 정의하고, 이를 해석할 수 있는 기성 파서를 제공합니다.

핵심 특징은 다음과 같습니다.

• 파이썬 문법의 부분 집합(subset) 을 기반으로 설계
• 실제 실행은 하지 않으며, 주석의 구조를 읽는 데만 집중
• 파서와 무관하게 다른 언어나 도구에서도 재구현 가능

즉, 특정 도구에 종속되지 않는 공통 주석 언어를 제공하는 것이 목적입니다.

---

Action Comment 언어의 기본 구조

이 표준에서 의미 있는 주석은 세 가지 요소로 구성됩니다.

1. Key
   • 보통 주석을 사용하는 도구의 이름
   • 파이썬 식별자(identifier)로 허용되는 문자열
2. Action
   • 해당 줄에서 수행할 동작의 이름
   • 역시 파이썬 식별자 형식
3. Arguments(인자 목록)
   • 동작과 연관된 추가 정보
   • 대괄호([]) 안에 작성하며, 선택 사항

예시: Mypy 규칙 무시 주석

# type: ignore[error-code]

• Key: type
• Action: ignore
• Arguments: error-code

인자 없이 사용하는 경우

# type: ignore

이 경우에도 내부적으로는 빈 인자 리스트로 처리됩니다.

---

인자(Arguments)로 사용할 수 있는 데이터 타입

인자 목록에는 다음과 같은 값들을 사용할 수 있습니다.

• 파이썬 식별자 (문자열로 해석)
• 하이픈(-)으로 연결된 두 식별자 (공백 허용)
• 문자열 리터럴
• 숫자 리터럴 (int, float, complex)
• 불리언 (True, False)
• None
• ... (ellipsis)
• 기타 파이썬 코드
  • 기본적으로 비활성화
  • 활성화 시 AST 객체 형태로 전달 가능

모든 문법은 파이썬 원본 문법과 동일하며, 단 멀티라인 표현은 허용되지 않습니다.

---

여러 개의 Action Comment를 함께 사용하는 방법

하나의 코드 라인에서 여러 도구를 위한 주석도 작성할 수 있습니다.
이 경우 # 기호로 이어서 작성합니다.

# type: ignore # <- mypy용 주석 # fmt: off # <- Ruff용 주석

• Action Comment 형식이 아닌 일반 주석은 파서에서 자동으로 무시됩니다.
• 기존 도구에서 사용하는 주석 문법 대부분은 이 표준으로 표현 가능하거나 쉽게 변환할 수 있습니다.

---

이 표준이 가지는 의미와 기대 효과

이 라이브러리가 제공하는 Action Comment 표준은 다음과 같은 가치를 가집니다.

• 사용자 입장
  • 도구별 주석 규칙을 외울 필요가 줄어듭니다.
  • 여러 도구를 함께 사용할 때 주석 충돌 걱정이 줄어듭니다.
• 도구 개발자 입장
  • 주석 파싱 로직을 직접 구현할 필요가 없습니다.
  • 일관된 규칙을 기반으로 안정적인 기능 구현이 가능합니다.

---

이 글에서 살펴본 Action Comment 표준 라이브러리는
파이썬 생태계에서 오랫동안 암묵적으로 사용되던 특수 주석 문법을 명확한 규칙으로 정리한 시도입니다.

• 파이썬 문법 기반의 단순한 구조
• 도구 간 공통으로 사용할 수 있는 주석 언어
• 사용자와 도구 개발자 모두의 부담을 줄이는 접근 방식

앞으로 더 많은 코드 분석 도구들이 이러한 표준을 채택한다면,
파이썬 개발 환경은 더 예측 가능하고, 더 일관된 방향으로 발전할 수 있을 것으로 기대됩니다.

300x250

https://github.com/pomponchik/metacode

GitHub - pomponchik/metacode: A standard language for machine-readable code comments