【python】PEP8に準拠したdocstringの書き方

# PEP8規約を守らないと犬に吠えられる!?
pythonには，スタイルガイド，コーディング規約としてPEP8というものがあります．
チームでの場合は，PEP8規約を満たすのかコードをチェックすることにより，共通の書き方に揃い，より可読性が高くなると同時に開発がしやすくなります．
PEP8をチェックするのはgithubなどにpushするとき，またはpull requestを作るときが考えれられます．そういった段階でCIツールを利用して，テストをおこない，規約に反する箇所を知らせてくれます．
そういったツールの一つとして，[reviewdog](https://github.com/reviewdog/reviewdog)というものがあります．
<img width=200 alt="ファイル名" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/407322/2e3b9f57-968d-359a-d005-5b47fd60285b.png">

PEP8規約に反する行動をとると，この犬に吠えられるのです．．
<img width=400 alt="ファイル名" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/407322/13ca7525-7fa2-d3e8-46e9-93764b9b9cc5.png">

私は，docstringに関するエラーH404，H405というもので犬に吠えられ続けて，頑張ってコードを直して犬に許してもらった話です．

# エラーコードH4xxの内容

H4xx 系のエラーコードは**docstring**に関するものになります．
docstringとは，関数やクラスメソッドを作成したときにその関数についての記述を行う場所です．
ちなみにこの良さそうに見えるdocstring, これだと犬に吠えられます！！（PEP8に完全には準拠していない）

```python
def docstring_sample(hoge1: str):
    """ 
    ここがdocstringです．

    引数がある場合はここで説明したりします．（何個かテンプレートみたいなのがあるのでそれはそれで調べてみてください）
    今回はnumpyスタイルで

    Parameters
    ----------
        hoge1 : str
            ここに入力された文字列を出力する"""
    print(hoge1)

```


他にもいろいろなことに関するエラーコードがあり[こちら](https://blog.sideci.com/about-style-guide-of-python-and-linter-tool-pep8-pyflakes-flake8-haking-pyling-7fdbe163079d)に素晴らしくまとまっています！

では，4xxの内容を見ていきましょう！

- [H401] Docstrings should not start with a space.
- [H403] Multi line docstrings should end on a new line.
- [H404] Multi line docstrings should start without a leading new line.
- [H405] Multi line docstrings should start with a one line summary followed

英語が苦手な僕は，H404とH405の理解に苦しみました...
では訳します（意訳です）

- [H401] Docstringsの記述はスペースから始めてはいけません．
- [H403] 複数行のdocstringを書く場合は，最後の行で改行してから閉じなさい．
- [H404] 複数行のdocstringを書く場合は，最初に1行空けてから書きなさい.
- [H405] 複数行のdocstringを書く場合は，1行その関数に関するまとめを書いてから書きはじめなさい．

ということです．

これを読んだときの僕は，
「なるほど，ということは先程のサンプルでは，最後に改行がない所，最初に一行空けてないところがだめだったんだ，書き直そう」
ということは，こんな感じか

```python
def docstring_sample(hoge1: str):
    """ 

    引数hoge1を出力する関数．（最初まとめを書けって言われたから）
    ここがdocstringです．

    引数がある場合はここで説明したりします．（何個かテンプレートみたいなのがあるのでそれはそれで調べてみてください）
    今回はnumpyスタイルで

    Parameters
    ----------
        hoge1 : str
            ここに入力された文字列を出力する
    """
    print(hoge1)

```

ところが，これでは**犬に吠えられます**．
エラーコードはH405です．
なぜだ．．っというので数時間溶かしました．
（僕のところでは犬に吠えられる限りmasterにマージできないルールなのです．．．）

# 対処法

数時間していろいろやってみた結果，やっと犬に認められました！！
それは

### H405はdocstringの一番最初に書く！

つまり，一行改行するまえにサマリを書く-> 一行改行するということです．

ようやく，PEP8規約に準拠したdocstringができました！

```python
def docstring_sample(hoge1: str):
    """引数hoge1を出力する関数．
    
    ここがdocstringです．
    引数がある場合はここで説明したりします．（何個かテンプレートみたいなのがあるのでそれはそれで調べてみてください）
    今回はnumpyスタイルで

    Parameters
    ----------
        hoge1 : str
            ここに入力された文字列を出力する
    """
    print(hoge1)

```
ちなみに一行しかdocstringを書かない場合は文末の`"""`は改行しなくていいです．

```python
def docstring_sample(hoge1:str):
    """引数hoge1を出力する関数"""
    print(hoge1)
```

# まとめ

PEP8の中には，流石にこれは無視してよくね？っていうのが何個かあると思います．（1行の文字数制限とか）
だけど，そこで自分を律して律儀に書くと，それはそれで達成感ありますよ！
ぜひやってみてください！

下に参考文献を載せておきます！
numpyスタイルは僕も参考にしていつも使わさせていただいています！すごくわかりやすくてありがとうございます！

# 参考文献
https://blog.sideci.com/about-style-guide-of-python-and-linter-tool-pep8-pyflakes-flake8-haking-pyling-7fdbe163079d

[[Python]可読性を上げるための、docstringの書き方を学ぶ（NumPyスタイル）](https://qiita.com/simonritchie/items/49e0813508cad4876b5a)