Clean ABAP ⑩ 주석 쓰는 법과 안 써도 되는 주석

3줄 요약

• 무엇을 하는지는 이름과 코드 구조로 표현하고, 주석에는 그렇게 작성한 이유를 남겨요.

• 설명은 관련 코드 바로 위에 쓰고, 필요 없어진 코드의 이력은 버전 관리에서 확인해요.

• 코드를 그대로 반복하는 주석과 수동 변경 이력은 유지할 정보만 늘릴 수 있어요.

어떤 상황에서 쓰나요

코드마다 주석을 붙였는데도 읽기 어렵다면 이름이나 메서드 구조부터 살펴볼 필요가 있어요. 이번 글에서는 코드로 드러낼 내용과 주석으로 남길 이유를 구분해 봐요. 오래된 코드와 변경 이력을 주석으로 쌓아 두지 않는 이유도 알아봐요.

코드가 무엇을 하는지는 이름과 구조로 드러내고, 선택의 이유는 주석으로 보충하면 읽기 쉽습니다. 아래 그림의 메모처럼 코드만으로 알기 어려운 이유를 남기는 데 집중해 보세요.

핵심 내용

코드로 표현하기

• 일(day) 값이 그달의 마지막 날짜를 넘었을 때 보정하는 코드를 예로 들어요. 원문은 DO 3 TIMES 안에 주석이 줄줄이 달린 하나의 메서드를 correct_day_to_last_in_month, is_invalid, reduce_day_by_one 세 메서드로 나눠 설명이 필요 없게 만들어요.

• 이 예에는 성능 반론도 소개돼요. 샘플 측정에서 리팩터링한 코드가 원래 코드보다 2.13배 느렸어요(9.6마이크로초 대 4.5마이크로초, 입력 31-02-2018). 아주 자주 불리는 고성능 애플리케이션에서는 문제가 될 수 있지만 일반 사용자 입력 검증에는 허용 가능하다는 입장이에요.

• 나쁜 이름을 주석으로 보충하기 전에 이름을 고쳐요. check_table( input )에 "테이블에 항목이 있는지 확인" 주석을 달기보다 has_entries( input )으로 이름을 고쳐요.

• 구간을 나누는 주석(" Build statement)은 메서드로 대체해요. 이렇게 하면 구간 사이에 임시 변수가 지워지지 않아 생기는 오류도 막아요.

좋은 주석

• "왜"를 써요. " can't fail, existence of >= 1 row asserted above 처럼요. " select alert root from database by key는 코드를 한국어로 되풀이한 것일 뿐이에요.

• 설계 설명은 설계 문서에 쓰고, 코드에는 링크 정도만 남겨요. 코드를 쓰기 위해 교과서를 읽어야 한다면 설계를 다시 보라는 신호예요.

• 마커는 FIXME(아직 작은 오류), TODO(곧 끝낼 일), XXX(동작하지만 더 나을 수 있는 코드)를 쓰고 내 닉네임이나 이니셜을 같이 적어요.

• ABAP Doc은 다른 팀을 위한 공개 API 에만 써요. 모든 주석처럼 빨리 낡아서 오해를 부르니까요.

형식

• * 대신 "를 써요. "는 문장과 같이 들여쓰기가 되지만 *는 엉뚱한 곳에 붙어요.

• 설명할 문장 앞줄에 써요. 뒤줄도, 줄 끝 주석도 덜 좋아요.

• 지운 코드를 주석으로 남기지 않아요. 테스트가 모두 통과하면 필요 없는 코드이고, 이력은 버전 관리에서 복원할 수 있어요. 영구 보존이 필요하면 $TMP 나 HOME 오브젝트에 복사해 둬요.

• 수동 버전 표시(* ticket 800034775 ABC ++ Start)는 하지 않아요. 변경 이유는 형상 관리와 이관 요청 텍스트가 더 알맞아요.

• 메서드 시그니처 주석(<SIGNATURE> 블록)과 ENDIF. " IF has_entries = abap_false, ENDMETHOD. " get_kpi_calc 같은 끝 주석은 불필요한 반복이에요. 오늘날 IDE(SE24, SE80, ADT)에서는 시그니처가 쉽게 보이고 메서드도 짧아졌어요. ADT 에서는 메서드 이름을 선택하고 F2를 누르면 돼요.

• 메시지 텍스트를 주석으로 복제하지 않아요. 메시지는 코드와 따로 바뀌어서 낡고 오해를 불러요. ADT에서 메시지 ID를 선택하고 F2를 누르면 텍스트를 볼 수 있고, 더 분명히 하려면 create_alert_not_found_message 같은 메서드로 뽑아요.

• ATC 경고를 숨길 때는 의사 주석("#EC NEEDED)보다 프라그마(##NEEDED)를 써요. 대응표는 프로그램 ABAP_SLIN_PRAGMAS 나 테이블 SLIN_DESC에서 찾을 수 있어요.

한국 현장에서는

변경 이력 주석("2024.03 홍길동 수정)이 관행인 곳이라면 위의 "수동 버전 표시는 하지 않는다"가 팀 표준과 충돌할 수 있어요. 변경 관리 기준이 감사 요건과 얽혀 있다면 가이드를 따르기보다 팀과 먼저 협의하세요. 이 글에서 감사 요건을 확인한 것은 아니에요.

주의할 점

• 리팩터링하면 느려질 수 있다는 측정치(2.13배)는 원문의 샘플 측정이고, 환경에 따라 달라요. 저는 이 숫자를 재현해 보지 못했어요.

• * 주석 금지는 취향이 갈리는 규칙이에요. 기존 프로그램의 * 주석 스타일과 섞이는 것이 불편하다면 팀 합의가 먼저예요.

• 원문은 2019년 첫 공개, 2025년 3월 마지막 수정본이에요. 이 글은 읽고 정리한 것이고, 예제를 직접 돌려 보지는 않았어요.

원문 주소: https://github.com/SAP/styleguides/blob/main/clean-abap/CleanABAP.md#comments