はじめに
Twitterで一時期流行していた 100 Days Of Code なるものを先日知りました。本記事は、初学者である私が100日の学習を通してどの程度成長できるか記録を残すこと、アウトプットすることを目的とします。誤っている点、読みにくい点多々あると思います。ご指摘いただけると幸いです！
今回学習する教材
-
- 8章構成
- 本章216ページ
-
第7章：協働作業
すべての関数、クラス、モジュールについてドキュメンテーション文字列を書く
Pythonは、__doc__でドキュメンテーション文字列を取り出せます。
ドキュメンテーション文字列は、3連二重引用符 (""") を使います。
def sampledoc(word):
"""ドキュメンテーションはアクセス可能です。"""
pass
print(repr(sampledoc.__doc__))
実行結果
'ドキュメンテーションはアクセス可能です。'
ドキュメンテーション文字列は、関数、クラス、モジュールに付与することができます。
モジュールのドキュメンテーション
このドキュメンテーション文字列の目的は、モジュールとその内容の紹介です。
1行目は、モジュールの目的を述べる1文、その次の段落は、モジュールの全ユーザが知るべき動作の詳細を記述します。
クラスのドキュメンテーション
ほぼモジュールのドキュメンテーション文字列と同じ形式です。
1行目は、クラスの目的を述べる1文、次の段落は、クラスの演算の詳細を記述します。
それ以降の段落は、以下の情報を記述します。
- クラスの重要なパブリック属性とメソッド
- プロテクテッド属性やスーパークラスのメソッドを正しく扱うためのサブクラスに対するガイド
関数のドキュメンテーション
モジュールやクラスと同じ形式です。
1行目は、関数が何をするか記述します。
次の段落は、振る舞いと引数、戻り値があれば戻り値も記述します。
呼び出し元が関数のインターフェースの一部として扱う例外は説明します。
関数のドキュメンテーション文字列を書く際の重要な注意事項
- 関数が引数を持たず単純な戻り値を返すなら、1文の記述で十分
- 関数が何も返さないなら、「returns None」と書くよりは戻り値について何も書かない方がよい
- 関数が通常の演算で例外を起こさないはずなら、それについては何も述べない
- 関数が可変長引数を取るなら、引数リストの中で*argsと**kwargsをその目的とともに述べる
- 関数がデフォルト値のある引数を取るなら、そのデフォルト値について述べる
- 関数がジェネレータなら、ドキュメンテーション文字列でジェネレータが何をyieldするか述べる
- 関数がコルーチンなら、ドキュメンテーション文字列でコルーチンが何をyieldし、yield式から何を受け取ると期待し、いつイテレーションを止めるかを述べる
隔離された複製可能な依存関係のために仮想環境を使う
Pythonを使うとき、パッケージをインストールするために、pipを実行することが多々あると思います。その際、依存パッケージもインストールしてきます。
この際に、複数のパッケージが同じ依存パッケージを要求する場合があると思います。例として、Sphinxパッケージと、flaskパッケージが依存しているパッケージをみてみます。
pip show Sphinx
---
Name: Sphinx
Version: 3.4.3
Requires: docutils, Jinja2, setuptools # ...略
pip show flask
---
Name: Flask
Version: 1.1.2
Requires: Werkzeug, Jinja2, click, itsdangerous
Sphinxとflaskのパッケージは、ともにJinja2パッケージに依存していることが分かります。
これは、Jinja2が新しいバージョンに移行して、最新版に更新した場合に、flaskは問題なく動くのに、Sphinxは動かないというような状況が起こり得るということを意味しています。
このような問題は、Pythonが1つのモジュールに1つのバージョンしか持てないことが原因です。
このようなバージョンによる動作の問題は、協働作業の場合、より顕著になります。
バージョンが異なることにより、コードベースがあるプログラムのマシンでは動くのに、他の人のでは動かないということが起こり得ます。
こういった問題を解決する方法は、pyenvやdockerなどの仮想環境を利用することです。
pyenvは、パッケージの明示した版とその依存関係を完全に別のディレクトリ構造にインストールします。全く同じ環境を整えることで、バージョンによる破綻を避けることができます。