클린 코드 책읽기 day4 - 4장 주석

요약

주석은 왠만하면 쓰지 마라.

주석을 쓸 수 밖에 없는 상황은 결과를 경고하거나 TODO정도이다.

 

---

책 내용

좋은 주석

법적인 주석

소스 파일 첫버리에 저작권 정보와 소유권 정보를 넣기도 한다

의도를 명료하게 밝히는 주석

주석은 올바른지 검증이 어려움으로 주석이 아닌 방법으로 코드를 표현할 방법이 없는지 검토해야한다.

 

결과를 경고하는 주석

때로 다른 프로그래머에세 결과를 경고할 목적으로 주석을 사용한다. 예를 들어 특정 테스트 케이스를 꺼야하는 이유를 설명하는 주석이다.

 

1. 테스트 스킵하기

import unittest

class MyTestCase(unittest.TestCase):
    @unittest.skip("이 테스트는 현재 작동하지 않습니다.")
    def test_currently_not_working(self):
        # 테스트 코드

    @unittest.skipIf(sys.version_info < (3, 7), "Python 3.7 이상에서만 실행")
    def test_new_feature(self):
        # Python 3.7 이상에서만 사용 가능한 기능 테스트

    @unittest.skipUnless(sys.platform.startswith("win"), "Windows에서만 실행")
    def test_windows_specific(self):
        # Windows 특정 테스트

2. 예상되는 실패 표시 (`@unittest.expectedFailure` 데코레이터 사용):

class MyTestCase(unittest.TestCase):
    @unittest.expectedFailure
    def test_known_bug(self):
        # 아직 해결되지 않은 버그를 테스트
        self.assertEqual(buggy_function(), expected_result)

3. pytest를 사용한 방법 (unittest 대신 pytest 사용 시):

import pytest

@pytest.mark.skip(reason="이 테스트는 현재 작동하지 않습니다.")
def test_currently_not_working():
    # 테스트 코드

@pytest.mark.xfail(reason="알려진 버그")
def test_known_bug():
    # 아직 해결되지 않은 버그를 테스트

@pytest.mark.parametrize("input,expected", [
    (1, 2),
    (2, 4),
    (3, 6)
])
def test_multiplication(input, expected):
    assert input * 2 == expected

TODO 주석

프로그래머가 필요하다고 여기지만 당장 구현하기 어려운 업무를 기술한다. 

요즘 대부분의 IDE는 TODO 주석을 전부 찾아 보여주는 기능을 제공해 주석을 잊어버릴 염려는 없다. 

 

 

---

읽고 느낀점

나는 평소에 주석을 전역 변수 선언부, 메인 logic 등 뭔가 코드들의 집합들의 위치를 좀 잘 보이게 하려고 쓰기도 했는데 이런 주석이 가독성에 도움을 준다고 생각했다. 전역 변수 선언 부를 class로 만들어서 표현하는게 좋다

ㅊ

class Config:
	MAX_ITEM = int: 100
    DEBUG_MODE = bool: False