Python開発: docstringでコードの可読性と保守性を向上させよう！

# はじめに
Pythonでは関数やクラス、モジュールなどにドキュメント文字列(docstring)を追加することでコードの理解を助け、保守性を向上させることができます。
この記事ではdocstringの基礎から記述方法、便利なVSCodeの拡張機能について解説します。

## docstringとは
docstringは、コードの構造体(関数、クラス、モジュールなど)に関連する説明を含む文字列です。
`""" """`で囲まれたコメントを記述することで、Pythonのhelp()関数やIDEがこの情報を活用でき、実装時にIDEが使用するメソッドなどでdocstringを表示してくれるためコードの理解が容易になります。

### docstringがない場合
![docstringなし.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3314085/c42e1cf9-d68f-d15d-574c-518d4bc4fa9b.png)


### docstringがある場合
![docstringあり.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3314085/9c0123e6-4adf-63a3-88c6-494ae89f79f4.png)

docstringが有ることで関数を使い方がよく分かりますね。

## docstringのスタイル
Pythonにはいくつかの標準的なdocstringスタイルがあります。
一般的なものは、以下のスタイルです。

- Googleスタイル
- NumPyスタイル
- Sphinxスタイル(reStructuredText)

個人的にGoogleスタイルが好みでよく使用しており、今回はGoogleスタイルを主に解説します。

## docstringの書き方(Googleスタイル)


サンプルコードはGoogleのスタイルガイドから引用しています。

https://google.github.io/styleguide/pyguide.html

### モジュールのdocstring
モジュールの冒頭には、そのモジュールの目的と機能を説明するdocstringを記述します。
- モジュールの全体的な目的
- 使用されるクラスや関数の概要
- 使用例

#### サンプルコード
```python
"""A one-line summary of the module or program, terminated by a period.

Leave one blank line.  The rest of this docstring should contain an
overall description of the module or program.  Optionally, it may also
contain a brief description of exported classes and functions and/or usage
examples.

Typical usage example:

  foo = ClassFoo()
  bar = foo.FunctionBar()
"""
```

### 関数およびメソッドのdocstring

関数やメソッドでは以下を記述します
- 概要
- 引数(Args)
各引数名、型、説明を記述
- 戻り値(Returns)
戻り値の型と内容を記述(戻り値がNoneのみを返す場合は不要)
- 例外(Raises)
発生する例外を記載

:::note note
関数やメソッドが以下に当てはまる場合は特にdocstringの記載する必要性が高いです。
- モジュールやクラスの外部からアクセス可能な関数やメソッド
- 処理内容が直感的に分かりにくい場合(アルゴリズムや複雑な処理を含む場合)
- サイズが大きい(関数やメソッドが大規模で多くの処理を含む)場合
:::

#### サンプルコード
```python
def fetch_smalltable_rows(
    table_handle: smalltable.Table,
    keys: Sequence[bytes | str],
    require_all_keys: bool = False,
) -> Mapping[bytes, tuple[str, ...]]:
    """Fetches rows from a Smalltable.

    Retrieves rows pertaining to the given keys from the Table instance
    represented by table_handle.  String keys will be UTF-8 encoded.

    Args:
        table_handle: An open smalltable.Table instance.
        keys: A sequence of strings representing the key of each table
          row to fetch.  String keys will be UTF-8 encoded.
        require_all_keys: If True only rows with values set for all keys will be
          returned.

    Returns:
        A dict mapping keys to the corresponding table row data
        fetched. Each row is represented as a tuple of strings. For
        example:

        {b'Serak': ('Rigel VII', 'Preparer'),
         b'Zim': ('Irk', 'Invader'),
         b'Lrrr': ('Omicron Persei 8', 'Emperor')}

        Returned keys are always bytes.  If a key from the keys argument is
        missing from the dictionary, then that row was not found in the
        table (and require_all_keys must have been False).

    Raises:
        IOError: An error occurred accessing the smalltable.
    """
```

### クラスのdocstring
クラスでは以下を記述します:

- 概要
- 属性(Attributes): インスタンス変数の説明を記述

```python
class SampleClass:
    """Summary of class here.

    Longer class information...
    Longer class information...

    Attributes:
        likes_spam: A boolean indicating if we like SPAM or not.
        eggs: An integer count of the eggs we have laid.
    """

    def __init__(self, likes_spam: bool = False):
        """Initializes the instance based on spam preference.

        Args:
          likes_spam: Defines if instance exhibits this preference.
        """
        self.likes_spam = likes_spam
        self.eggs = 0

    @property
    def butter_sticks(self) -> int:
```

## docstringを書く際におすすめなVSCode拡張機能

VSCodeにはdocstringを書くときに便利な拡張機能があるため紹介します。
autoDocstringという拡張機能をダウンロードすることで、関数やクラスに"""を入力し、Enterキーを押すだけ(右クリックからGenerate Docstringでも呼び出し可能)で引数や戻り値に関するテンプレートが自動生成されるため非常に便利です。

![docstring.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3314085/c6216c07-f894-e3c8-a67a-10ce0c5c4360.png)

#### docstringのテンプレート自動生成実演
![docstring自動生成.gif](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3314085/fc9c3d52-bda6-8541-3805-d4548f35ee88.gif)

## まとめ
docstringは、Pythonコードの可読性とメンテナンス性を大幅に向上させる強力な手段です。
ぜひ実装コードに取り入れてみてください！