Speaker

ku-mu (@cocodrips) さん

資料

Youtube Live https://youtu.be/2A3gRyT54Wc
Slide Share https://www.slideshare.net/cocodrips/docstring-pyconjp2019

あらまし

メンテナンスしやすいコードを書くために、docstringを書いてみよう

何が嬉しい？

引き継ぎ。未来の自分とチームメイトに優しい
実装と同じ場所に記述するので、改修時にメンテし忘れるリスクが（別立てで書くよりも）少ない
引数／戻り値の型を宣言しておくと、IDEの便利機能（型チェックや補完）が利用できる
- なお type hint でも同様のことが可能
docstringからAPIのドキュメンテーションを自動生成できる（sphinxを利用する）

書き方

以下の例は、（たぶん）デファクトスタンダードであるreSTスタイルでの記述。

def func(arg1, arg2):
  """関数の概要を1行で書く
  
  0行以上の詳細情報を書く。
  省略することも可能

  :param arg1: arg1引数の概要
  :type arg1: int  # arg1の型
  :param arg2: arg2引数の概要
  :type arg2: str  # arg2の型
  :rtype: book  # 戻り値の型
  :return: 返り値の説明
  """

参考: Youtube live (8:40付近)

↑は必ずしも全部書く必要はなくて（動作に支障ないので）、とりあえずでも始めてみると良い。とりあえず、まずは概要だけでも。（詳細な挙動に関する遺言とかを残しておくとよりGood

また、上記の記述のうち型情報に関してはtype hintを書いてればdocstringへの記述は不要。

type hintを使って上記の例を記述し直すと以下のようになる。

def func(arg1: 型, arg2: 型): -> 返り値の型
  """関数の概要を1行で書く
  
  関数の詳細説明

  :param arg1: arg1引数の概要
  :param arg2: arg2引数の概要
  :return: 返り値の説明
  """

参考: Youtube live (13:40付近)

PyCharmやVSCodeのようなIDEにはdocstringのテンプレートを自動生成してくれる機能があるので、とっても有用。 ... 14:20付近

docstringのスタイル

3つほどある。

reST ... デファクトっぽい。上記の例はこの形式
NumPy ... 詳細な記述を書きやすいが、縦に長くなりがち。ただしreSTスタイルよりは人間が読みやすい
Google ... 書き手にとっても読み手にとってもシンプル。記述が横に長くなる傾向

上記のうち、どれを採用すべきかは基本的に自由。チーム内で統一が取れていれば何でも良い。

（Sphinxによる）ドキュメントの自動生成やtypehintを駆使していくならreSTスタイルがおすすめ。

Sphinxを利用したドキュメントの自動生成

15:18〜

docstringのカバレッジを計測する doc-cov

docstringを書くモチベーションになれば、と開発されたそうです。ユーザーもプルリクも絶賛募集中。

紹介記事 https://cocodrips.hateblo.jp/entry/2019/02/06/234630
PyPI https://pypi.org/project/doc-cov/

まとめ

docstringとsphinxによる自動生成、大昔に試みて何故か挫折していたので「もう１回ちゃんとやってみようかな🧐」と思うきっかけになりました。当時よりはテスト書いたりする意識やスキルが伸びてるはずなので、自分のコード品質を上げるためにやれることはやっていきたいなと前向きなテンションになれました。

doc-covはすごくよさそうです。ドキュメンテーションってテストと同様に敬遠されがちなところがあるなと（自分の実感も含めて）感じるので、こうした可視化ツールによってモチベーションを高めていく、というアイデアはイケてるなぁと。前日の「Pythonを使ったAPIサーバー開発を始める際に整備したCIとテスト機構」の発表にも共通しますが、敬遠されがちなものを楽しんで取り入れていこうとするメンタルが素敵やなと思いました。

※以下思いつき

CIサービスの1ジョブとしてdoc-covの実行を定義しておいて、自動的にSlackとかに「君の書いたdocstringはカバレッジ95%もあるぞ！すごーい！天才！！」みたいに通知してくれる仕組みとか作ったら開発がもっと楽しいものになりそうだと思いました。

「このdocstringは誰々が書いた」を判定する仕組みってどうやって実現するんでしょうね。いいアイデアがあれば知りたいです...