좋은 주석을 작성하는 방법

https://stackoverflow.blog/2021/12/23/best-practices-for-writing-code-comments/

Best practices for writing code comments

스택오버 플로우에 Best practices for writing code comments 라는 주제의 글이 올라왔다.  

이 포스팅에 작성된 내용을 읽고 새롭게 정리해 보았다.

Rule 1: 주석은 코드를 중복해서 작성하면 안 된다.

- 주석은 이미 코드에서 명확하게 드러나는 내용을 중복해서 설명하는 데 사용해서는 안 된다. 코드 자체가 의도를 명확하게 전달할 수 있도록 노력해야 한다.

# Bad 예시
x = 5  # x 변수에 5를 할당

# Good 예시
x = 5  # x 변수를 5로 초기화

Rule 2: 좋은 주석은 애매모호한 코드를 변명해주지 않는다.

- 주석은 코드의 애매모호한 부분을 해결해주는 것이 아닌, 코드의 목적이나 의도를 설명하는 데 집중해야 한다. 주석은 코드의 의미를 명확히 전달하거나 개선하는 역할을 해야 한다.

# Bad 예시
# 리스트를 순회하며 모든 요소의 합
for i in range(len(numbers)):
    sum += numbers[i]

# Good 예시
total = 0
for num in numbers:
    total += num  # 리스트의 요소들의 합을 계산

Rule 3: 명확한 주석을 작성할 수 없다면, 코드에 문제가 있을 수 있다.

- 주석이 필요한 정도로 코드가 복잡하거나 이해하기 어렵다면, 해당 코드 자체에 문제가 있을 수 있다. 코드를 다시 검토하고 개선하여 주석을 최소화할 수 있는 명확하고 간결한 코드를 작성해야 한다.

# Bad 예시
x = 5  # x를 5로 설정

# Good 예시 (명확성이 불가능한 경우, 코드를 개선하는 것을 고려)
speed = 5  # 속도를 상수값으로 설정

Rule 4: 주석은 혼란을 해소해야 하며, 혼란을 야기해서는 안 된다.

- 주석은 코드를 이해하는 데 도움을 주어 혼란을 해소해야 한다. 주석이 헷갈리거나 오해를 불러일으키는 경우는 피해야 한다. 명확하고 직관적인 주석을 작성해야 한다.

# Bad 예시
x = 5  # x를 1만큼 증가

# Good 예시
x = 5  # x를 5로 초기화
x += 1  # x를 1만큼 증가

Rule 5: 비표준적인 코드를 주석으로 한다.

- 비표준적인 코드나 특이한 방식으로 작성된 코드는 주석으로 설명해야 한다. 왜 특정 방식으로 작성되었는지, 어떤 이점이 있는지 등을 설명하여 코드를 이해하기 쉽게 도와야 한다.

# Bad
# 숫자들의 평균 계산
average = sum(numbers) / len(numbers)

# Good
# sum() 함수를 사용할 수 없으므로 평균을 직접 계산
average = total(numbers) / count(numbers)

Rule 6: 복사한 코드의 원본 소스에 대한 링크를 제공한다.

- 만약 다른 소스에서 코드를 복사한 경우, 주석에 해당 코드의 원본 소스에 대한 링크를 제공하는 것이 좋다. 이는 코드의 출처를 명시하고 참조할 수 있도록 도와준다.

# 참고 코드 : https://example.com/source/file.py
def calculate_average(numbers):
    # 코드 구현
    return average

Rule 7: 외부 참조 자료가 가장 유용한 곳에 링크를 포함한다.

- 코드와 관련된 외부 참조 자료가 있을 경우, 해당 자료가 가장 유용하게 활용될 수 있는 위치에 링크를 포함해야 한다. 이는 다른 개발자들이 필요한 정보를 쉽게 얻을 수 있도록 도와준다.

# https://example.com/documentation 참고 
def process_data(data):
    # 코드 구현

Rule 8: 버그를 수정할 때 주석을 추가한다.

- 버그를 수정하는 과정에서 주석을 추가하는 것은 좋은 습관이다. 수정한 내용이나 버그 해결 방법을 주석으로 남겨두면, 나중에 동일한 문제를 다시 마주칠 때 유용한 정보가 될 수 있다.

def divide(a, b):
    # 0으로 나누는 오류를 피하기 위해 b가 0인지 확인
    if b != 0:
        return a / b
    else:
        # 오류를 기록하고 None을 반환합니다.
        log_error("0으로 나누기 시도.")
        return None

Rule 9: 미완성된 구현을 표시하기 위해 주석을 사용한다.

- 아직 완성되지 않은 구현이나 작업을 주석으로 표시하는 것은 도움이 된다. 이는 다른 개발자들이 해당 부분을 인지하고 이해할 수 있도록 도와주며, 나중에 작업을 이어나갈 때 유용한 안내가 될 수 있다.

def process_data(data):
    # TODO: 엣지 케이스에 대한 오류 처리 구현
    # 코드 구현

이와 같은 주석으로 협업을 할 때 코드의 의미를 더 나은 방법으로 전달할 수 있다.
그 외에도 vscode 의 Extensions 을 활용하여 이런 방법으로 나타내는 것도 좋다.

---

TODO: 아직 해결되지 않은 작업이나 구현이 필요한 부분을 나타낸다.  

# TODO: 엣지 케이스에 대한 오류 처리 구현
# 코드 구현

FIXME: 버그 수정이 필요한 부분을 나타낸다.

# FIXME: 0으로 나누는 오류 처리 필요
def divide(a, b):
    if b != 0:
        return a / b
    else:
        log_error("0으로 나누기 시도")
        return None

NOTE: 참고 사항이나 중요한 정보를 나타낸다

# NOTE: 이 알고리즘의 시간 복잡도는 O(n^2)
def algorithm(data):
    # 코드 구현

DOCS: 외부 주소를 표현한다.

# DOCS: [링크](https://example.com/documentation) 
def process_data(data):
    # 코드 구현​

 

Best practices for writing code comments 글을 읽어보고 많은 생각이 들었다.

 

누군가는 코드를 클린하게 작성하면 주석은 필요 없다 주장하는 개발자가 있고, 클린하게 코드를 작성 하였더라도 제 3자가 읽었을 때 이해하지 못할 수 있기 때문에 약간의 주석은 필요하다고 주장하는 개발자가 있다. 

 

뭐가 잘 못 되었고 뭐가 맞는지 정답은 없다. 그저 개인이 선호하는 방식과 팀에 따라 컨벤션을 정해 방법을 선택하면 좋을 듯 하다.

그리고 한달 후에 내가 작성한 코드를 리뷰해보면 좋은 코드였는지, 필요한 주석 이었는지 되돌아 볼 수 있는 것 같다.