클린코드 챌린지 Day 06

오늘 TIL 3줄 요약

나쁜 코드에 주석을 달지 마라. 새로 짜라.
자신이 저지른 난장판을 주석으로 설명하려 애쓰는 대신에 그 난장판을 깨끗이 치우는데 시간을 보내라!
좋은 주석은, 주석을 달지 않을 방법을 찾아낸 주석이다.

TIL (Today I Learned) 날짜

2022.04.28 - 2022.04.29

오늘 읽은 범위

4장. 주석

나쁜 코드에 주석을 달지 마라. 새로 짜라.
- 브라이언 W. 커니핸, P.J 플라우거

경솔하고 근거 없는 주석은 코드를 이해하기 어렵게 만든다.
오래되고 조잡한 주석은 거짓과 잘못된 정보를 퍼뜨린다.

주석을 작성하기 전에 한번 리마인드하면 좋은 말들로 시작을 연다.

주석은 나쁜 코드를 보완하지 못한다.

자신이 저지른 난장판을 주석으로 설명하려 애쓰는 대신에 그 난장판을 깨끗이 치우는데 시간을 보내라!

코드로 의도를 표현하라!

몇 초만 더 생각하면 코드로 대다수의 의도를 표현할 수 있다. 많은 경우 주석으로 달려는 설명을 함수로 만들어 표현해도 충분하다.

좋은 주석

법적인 주석 (라이센스 등)
정보를 제공하는 주석 (?)
의도를 설명하는 주석
의도를 명료하게 밝히는 주석 (위험할 수 있다.)
결과를 경고하는 주석
TODO 주석
중요성을 강조하는 주석

나쁜 주석

주절거리는 주석
이해가 안 되어 다른 모듈까지 뒤져야 하는 주석은 독자와 제대로 소통하지 못하는 주석이다.
같은 이야기를 중복하는 주석
코드보다 읽기가 쉽지 않고 부정확하여 독자가 함수를 대충! 이해하고 넘어가게 만드는 경우
오해할 여지가 있는 주석
의도는 좋았으나 코드를 잘못 이해하는 경우 사용자로 하여금 오동작을 유발할 수 있다.
의무적으로 다는 주석 (규칙에 의해 의무적으로 적는 주석)
이력을 기록하는 주석 (과거의 관례, Git으로 대체!)
있으나 마나 한 주석
당연한 사실을 언급하여 새로운 정보를 제공하지 못하는 경우, 개발자가 주석을 무시하도록 만든다.
함수나 변수로 표현할 수 있다면 주석을 달지 마라.
위치를 표시하는 주석
닫는 괄호에 다는 주석
공로를 돌리거나 저자를 표시하는 주석
주석으로 처리한 코드
HTML 주석
전역 정보
주석을 달아야 한다면 근처에 있는 코드만 기술해라.
너무 많은 정보
모호한 관계
함수 헤더

오늘 읽은 소감은? 떠오르는 생각을 가볍게 적어보세요

좋은 주석과 나쁜 주석에 대한 예제들을 통해 설명했지만 영어를 네이티브로 하지 않기에 크게 영감을 얻지는 못한 것 같다.

궁금한 내용이 있거나, 잘 이해되지 않는 내용이 있다면 적어보세요.

같이 코드를 작성하는 사람이 한국인이라면 한글로 작성해야하는지 궁금하다.

마지막 예시를 보다가 제곱근이 얼마나 시간을 더 단축하는지가 궁금해졌다.
파이썬으로 간단하게 구현해서 비교해보았다.

# Sieve of Eratosthenes
import time
import numpy as np

def find_prime_number(max_value):
    primeNumbers = np.arange(0,max_value,2)
    for i in range(3, int(np.sqrt(max_value))+1, 2):
        if i in primeNumbers:
            for j in range(i*i, max_value+1, i):
                if j in primeNumbers:
                    primeNumbers[primeNumbers == j] = 0
    return primeNumbers[primeNumbers > 0]

def find_prime_number_without_sqrt(max_value):
    primeNumbers = np.arange(0,max_value,2)
    for i in range(3, int(max_value), 2):
        if i in primeNumbers:
            for j in range(i*i, max_value+1, i):
                if j in primeNumbers:
                    primeNumbers[primeNumbers == j] = 0
    return primeNumbers[primeNumbers > 0]

# TEST_TIME과, MAX_NUMBER값을 크게 세팅한다면 테스트에 많은 시간이 소요될 수 있음
TEST_TIME = 10
MIX_NUMBER = 1e3
MAX_NUMBER = 1e5
randomTestNumbers = np.random.randint(MIX_NUMBER, MAX_NUMBER, TEST_TIME)

start = time.time()
for i in range(TEST_TIME):
    find_prime_number(randomTestNumbers[i])
end = time.time()
print("Time for finding prime number: %f" % (end - start))

start = time.time()
for i in range(TEST_TIME):
    find_prime_number_without_sqrt(randomTestNumbers[i])
end = time.time()
print("Time for finding prime number without sqrt: %f" % (end - start))

역시나 다수가 사용하는 것은 그럴만한 이유가 있는 법이다.
궁금하다면 직접 돌려 보시길!

지식의 유일한 원천은 경험이다

Clean Code 06