문자열을 더 다양하게 사용할 수는 없을까? (Raw String, docstring, 문서화)

🤔 Problem

오늘 포스팅은 어떤 문제점을 겪었다기보다는 새로운 것을 발견한 것에서 시작한 포스팅입니다. 많이 접한 문법이지만, 이것이 무엇인지 어떻게 활용할 수 있는지를 다루어보려 합니다.

 

오픈소스를 보면, 이런 코드들을 많이 보게 됩니다.

class Model(nn.Module):
    r"""
    param(1): ~~~할 때, ~~~로 지정
    param(2): ~~~할 때, ~~~로 지정
    """

    def __init__(self, param1, param2):
        super().__init__()

 

처음 파이썬을 공부할 때는 따옴표를 3번 쓰는 것이 여러 줄 주석이라는 개념으로 알고 있었지만, 시간이 지나서 다시 저걸 찾아봤을 때는 docstring이라 불리고 있었고, 문자열 앞에 붙는 r은 Raw String이라는 것을 의미하더라고요.

 

그래서, 이 두 가지 개념이 어떤 것인지 기록을 해두려고 합니다.

---

😀 Solution

1️⃣ docstring

docstring은 Documentation String의 줄임말입니다. 보통 코드를 문서화할 때, 많이 사용합니다.

일반적으로 오픈소스의 클래스, 함수, 모듈, 메서드라면 모두 어떤 역할을 하고, 사용하기 위해서는 어떤 것을 필요로 하는지 가이드라인이 필요합니다. docstring이 그 역할을 수행합니다.

 

docstring의 위치는 클래스, 함수, 메서드라면 선언 바로 아랫줄에 나타내고, 모듈이라면 코드의 첫 번째 줄에 나타냅니다.

그리고, 따옴표를 3개 사용해서 나타내면 docstring 선언이 끝납니다. 매우 간단해요!

 

그러면, 이 docstring(문서)를 어떻게 확인할까요? 이것도 간단합니다. docstring을 작성한 모듈, 클래스, 함수, 메서드에는 __doc__이라는 속성이 생깁니다. 이 속성이 문서의 내용을 담고 있는 문자열이기 때문에 그저 출력만 해주면 됩니다.

model = Model()

print(type(model.__doc__))
print(model.__doc__)
print(Model.__doc__)

#Output
<class 'str'>

    param(1): ~~~할 때, ~~~로 지정
    param(2): ~~~할 때, ~~~로 지정


    param(1): ~~~할 때, ~~~로 지정
    param(2): ~~~할 때, ~~~로 지정

그리고, 마지막으로 docstring의 특이한 점이 하나 있습니다.

docstring이 만약에 아래와 같이 작성된 경우를 봅시다.

class Model(nn.Module):
    """
    param(1): ~~~할 때, ~~~로 지정
    param(2): ~~~할 때, ~~~로 지정
    'str1 ' "str2"
        tab1
            tab2
    """

원래의 문자열을 선언을 하는 경우에는 줄 넘김, 따옴표, 공백(탭) 관련 문자를 넣기 위해서는 백슬래시로 이스케이프 문자를 나타내야 했습니다.

 

하지만, docstring은 그런 것으로 고려하지 않고, 정말 하나의 문서처럼 작성하며 이스케이프 문자 없이 그대로 출력할 수 있다는 점이 특이한 점이자 문서화를 할 때 편한 점입니다.

 

(+ 그러면 '이스케이프 문자로 나타낸 줄 넘김, 따옴표, 공백(탭)은 못 하는 것이냐?'라고 질문할 수 있습니다. 못 하지 않습니다. 여전히 그 기능들 또한 수행을 합니다.)

2️⃣ Raw String

docstring은 따옴표 3개로 나타낸다고 했는데, 맨 위의 예시에서는 따옴표 3개 앞에 r이라는 문자가 붙습니다.

이것이 의미하는 바는 docstring보다 더 간단하며, 이는 Raw String을 의미합니다.

 

Raw String의 r을 따서 나타내는 표현한 문법으로, 'Raw String이란 이스케이프 문자(백슬래시)를 전부 무시한다'는 의미를 가집니다.

 

예시를 나타내보면, 다음과 같습니다.

a = "abc\nabc"
b = r"abc\nabc"
print(a)
print(b)

#Output
abc 
abc
abc\nabc

문자열 b가 Raw String을 사용한 예시입니다. 이스케이프 문자가 적용하는 문법을 무시하고 백슬래시를 그대로 출력하는 것을 볼 수 있습니다.

3️⃣ docstring + Raw String

그래서 두 문법은 코드의 문서화를 위해 조합을 시켜 많이 사용합니다. 왜냐하면, docstring 단락에서 말한 것처럼 docstring을 사용하더라도 이스케이프 문자는 그대로 적용하기 때문에 문서에서 백슬래시 관련 문자를 출력하고 싶을 때, 두 조합을 많이 사용합니다. 

---

📂 Reference

https://wikidocs.net/16050

24. Docstring - 문서화