[Python] Comments and Docstrings

Comment

Python에서의 comment는 주석이라고 불리며, Python Interpreter가 아닌 사람을 위해 작성되는 것임.

 

Comment는 해당 code들이 무엇을 위해 존재하는지 등을 기재하여 개발자가 보다 쉽게 코드를 이해하고 유지 보수할 수 있도록 도와준다. 일반적으로 소스코드는 매우 복잡해지고 그 양이 많아질 수 있기 때문에, 적절한 위치에 해당 코드의 이해를 도울 수 있는 comment는 반드시 작성되어야 한다.

 

Python Interpreter는 #(Hash, Crosshatch, Sharp) 문자를 만나면, 해당 line의 이후 내용은 무시함 (즉, 실행하지 않음).

즉, # 문자를 line에서 첫 문자로 놓을 경우 해당 line 전체가 comment가 되고, 중간에 놓이면 그 뒷부분이 comment가 된다.

# line comment
c = 7 + 3 # This part is a comment

 

사실 comment는 debug와 같이 source code의 동작을 확인하고 수정할 때도 많이 사용된다. 일부 code를 동작시키지 않거나 특정상황에 맞춰 특정 code block만 동작시키기 위해서도 많이 사용된다.

 

참고로,
vscode등에서 특정 code block을 선택하고 CTRL+/ 를 누르며 선택된 block이 주석처리되고,
해당 block에 대해 다시 CTRL+/ 를 입력하면 주석해제가 됨.

---

Docstring

function이나 class를 설명해주는 comment들은

docstring(short for documentation string)이라고 불리며

보통 function body부분의 첫 라인에서 three double quotes (""")로 시작하고

여러 line에 걸져 주석이 이루어지고 (같은 indentation유지) three double quotes로 끝난다.

일반적으로 multi-line으로 작성되기 때문에
three double quotes 또는 three single quotes 로 시작하고 끝나야 하며 (강제적인 건 아님)
관례적으로 three double quotes가 사용됨.

 

다음 code는 간단한 function에서의 docstring을 보여줌.

def fn_name (argument0: int, argument1: int) -> int:
    """ This part is a docstring.
    It is multi-line comment!
    It is a description of what the function will do and is a text for humnas to read.

    >>> fn_name(4,7)
    11
    """

    # function body
    a = argument0+argument1

    return a

docstring은

function이나 class를 사용하는 개발자들(몇 주 후의 작성자 포함)을 위한 것으로

해당 function이나 class를 어떻게 사용해야하는지를 간략히 기술한다.

때문에 어떻게 사용하는지에 대한 간략한 예제와 I/O (parameter와 return value)들에 대한 설명으로 구성되는게 일반적이다.

 

다음과 같이 helf built-in function에 fn_name 함수 이름을 넣어주면 docstring으로 작성한 내용이 뜸.

help(fn_name)

 

fn_name 함수도 Python에서는 object이며, docstring에 해당하는 문자열을 내부 변수 __doc__에 저장하게 된다.

이를 확인하려면 다음과 같이 print<c/ode>문으로 확인 가능함.

print(fn_name.__doc__)