docstring:
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>
문서가 너무 많으면 읽는 사람에게도, 유지관리하는데에도 부담이 된다. (코드를 변경하면 문서도 매번 같이 변경해야 하기 때문에)
문석화를 너무 많이 하는것도 문제인데, 코드와 맞지 않게 잘못 작성하는건 더 심각한 문제다.
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)
문서를 읽는 사람은 어떤 함수를 사용하기 위해 이 함수가 어떻게 돌아가는 지는 알 필요가 없다.
만약 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