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

3줄 요약

• 주석으로 설명하기 전에 이름과 메서드로 표현하고, 주석은 "무엇"이 아니라 "왜"를 써요.

• * 대신 " 로, 문장 앞줄에 쓰고, 지난 코드는 주석 처리하지 말고 지워요.

• 시그니처 주석, 끝 주석, 메시지 텍스트 복제, 수동 버전 표시(ticket ... Start/End)는 소음이에요.

어떤 상황에서 쓰나요

주석이 없으면 불안하고, 있으면 지저분한 코드를 만난 적이 있을 거예요. 《Clean Code》는 주석을 금지하지 않아요. "더 나은 수단이 실패했을 때만 쓰라"고 말해요. 이번 회는 그 기준을 ABAP 에 맞게 풀어 쓴 주석 장을 정리해요.

핵심 내용

코드로 표현하기

• 날짜의 일(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