3.2 Documentation #Writing Idiomatic Python 3.1

oen·2022년 8월 28일
0

1. PEP-257의 docstring 컨벤션 따르기

docstring:

  • def, class의 바로 아래, 파일의 맨 위(Module 첫번째 줄)에
  • 따옴표 3개('''나 """)로 작성
  • public 혹은 라이브러리로 쓰일 수 있는(exported) 기능에는 반드시 docstring으로 문서화 해야 한다.
  • IDE에서도 지원하니까 여러모로 도움이 된다.

👎

def calculate(value_list):
	# summary of the code (ex: calculates various statistics for a list of numbers)
    <function body>

👍

def calculate(value_list):
	""" Return a tuple containing the mea, median,
    and mode of.a list of numbers
    
    Arguments:
    value_list -- a list of integer values
    
    """
    <function body>

2. 인라인 문서화는 최소로 하자

문서가 너무 많으면 읽는 사람에게도, 유지관리하는데에도 부담이 된다. (코드를 변경하면 문서도 매번 같이 변경해야 하기 때문에)

👎

문석화를 너무 많이 하는것도 문제인데, 코드와 맞지 않게 잘못 작성하는건 더 심각한 문제다.

def calculate_mean(numbers):
	"""Return the mean of a list of numbers"""
    
    # If the list is empty, we have no mean!
    if not numbers:
    	return 0
        
    # A variable to keep track of the running sum
    total = 0
    
    # Iterate over each number in the list
    for number in numbers:
    	total += number
   
   # Devide the sum of all the numbers by how
   # many numbers were in the list
   # to arrive at the sum. Returh this value
   return total / len(numbers)

👍

코드만으로 이해할 수 있도록 코드를 명료하게 작성하면 불필요한 주석을 줄일 수 있다.

 def calculate_mean(numbers):
	"""Return the mean of a list of numbers"""
    
	return sum(numbers) / len(numbers)

3. 어떻게 하는지가 아니라, 무엇을 하는지만 문서화하기

문서를 읽는 사람은 어떤 함수를 사용하기 위해 이 함수가 어떻게 돌아가는 지는 알 필요가 없다.

👎

만약 number가 소수인지 구하는 방식을 변경하면 함수의 문서도 같이 따라서 변경해야만 한다.

def is_prime(number):
	"""Mod all numbers from 2 -> number and return True
    if the value is never 0"""
    
    for candidate in range(2, number):
    	if number % candidate == 0:
        	print(candidate)
            print(number % candidate)
            return False
  	
    return number > 0

👍

함수의 구현 방식이 바뀌더라도 문서는 바뀔 필요가 없어야 한다.

def is_prime(number):
	"""Return True if number is prime"""
    
    for candidate in range(2, number):
    	if number % candidate == 0:
        	return False

	return number > 0
profile
🐾

0개의 댓글