Pythonで書いたコードを人に渡す前に、最低限やって欲しいこと

はじめに

パーソルのブログによると、2022年プログラミング言語おすすめランキング1位はPythonらしいです。
https://persol-tech-s.co.jp/hatalabo/it_engineer/607.html#_1-1
実際にPythonは人気の言語なので、ここ数年「Pythonでコードを書いたからアプリに組み込んで欲しい」という依頼がそれなりにあります。
しかし実際にコードを貰うと、可読性が低かったり、そもそも環境依存が強すぎてまともに動かなかったりするケースが多くて対応に苦労することが多いです。

ということで、仕事で人に渡すPythonのコードを書くなら最低限これくらいはやってくれと思うことを書いていきます。

とにかく最低限やってほしいこと

1. パッケージのバージョン管理してください
2. 関数やメソッドの引数と戻り値には、型アノテーションを定義してください

パッケージのバージョン管理をしてください

とある案件で貰ったPythonの環境情報環境が、Readmeにこんな感じで書いてあるだけでした。

■ 動作環境
・ Python
  ・ 3.9.6

■ 使用ライブラリ
・ Django
・ boto3
・ Pandas

Python本体以外のバージョン分からないですし、絶対他にもライブラリ使っているだろ、、、
適当にpip installして動かそうとしたら、もちろんエラーになりました。
いろいろ足りてないパッケージあったし、何よりPandasの正解のバージョン引き当てるのに苦労しました。

という感じで、インストールするだけで無駄に工数がかかるので、ちゃんとバージョン管理はしてください！!

とりあえず、pythonのバージョン管理にはpoetryを使おう

「バージョン管理ってどうすればいいの？」という人は、とりあえずpoetryを使いましょう。

poetryは何をしてくれるか？

nodeで言うところのnpmやyarnみたいなものです。

• 仮想環境を管理してくれる
• インストールするパッケージのバージョン管理をしてくれる
• パッケージの依存関係も解決してくれる

この記事では触りしか紹介しないので、実際に使う場合はググって使い方を調べるかドキュメントを読みましょう。
https://cocoatomo.github.io/poetry-ja/basic-usage/

環境やパッケージの管理は、pyproject.tomlというファイルを使って実施します。nodeで言うところのpackage.jsonみたいなものです。
参考に、以前私が作ったレポジトリに置いてあるものを貼っておきます。（最低限しか書いてないので、いいサンプルではないですが、、、）
https://github.com/k-ibaraki/sample-django-azure-webapps/blob/main/pyproject.toml
ライブラリをインストールする時に、poetryがpyproject.tomlを更新してくれるので、自動的に必要なライブラリの一覧が作られます。
他の人に配布する際にpyproject.tomlもセットでわたせば、他の人の環境でも同じライブラリが入った状態を再現できるということになります。
pyproject.tomlはpoetry用のファイルではなくPEP518で定義され標準化されていますので、配布先の相手がpoetry以外のパッケージ管理ツールを使っていても問題は無いはずです。

poetryの簡単な使い方

• プロジェクトにpoetryを導入
  • 仮想環境とpyproject.tomlが作られます

poetry init

• ライブラリの追加
  • 仮想環境にライブラリをインストールし、pyproject.tomlにも追加します

poetry add pandas

• pyproject.toml記載のパッケージをインストールする

poetry install

poetryを使えば、こんな感じで簡単にパッケージ管理をすることができるのでお勧めです。

関数やメソッドの引数と戻り値には、型アノテーションを定義してください

Pythonは動的型付け言語です。ですので型を書かなくても動きます。1人で開発するなら基本的に全てを理解しているはずなので、もしかしたら型を書かなくてもなんとかなっているかもしれません。しかし、そのコードを貰った人はそうとうツライです。

というのも動的型付けのデメリットとして、下記のようなモノが挙げられます。

• 人が見た時に分かりにくい
• 動かさないと型のエラーが発覚しない

つまり、他の人のコードにを読む時に型が付いていなければ、読むだけでは処理を理解するのが難しいので実際に動かしながら処理を追う必要があります。めちゃくちゃ時間がかかります。

さて、pythonは動的型付け言語ではありますが、型アノテーションを書ける仕様になっています。
少なくとも人に見られるところは型アノテーションを書いておけば、読んだ人が何となく使い方を理解しやすくなります。

def greeting(name: str) -> str:
    return 'Hello ' + name

https://docs.python.org/ja/3/library/typing.html

とりあえず、VSCodeで型アノテーションを書く手間を減らそう

「そうは言われても、型書くの面倒くさいよ。。。」と思った方、とりあえずVSCodeを使いPythonのエクステンションをONにしておきましょう。

VSCodeでPythonファイルを開くと、インストールを促してくるので、いつの間にか使っている人も多いはずです。
Pythonのエクステンションは、MicrosoftがPythonを開発に関する便利機能をまとめたもので、この中に入っているPylanceというやつが、型をいい感じに扱ってくれます。

例えば、こんな感じのpythonコードがあったとすると、、、

def get_hello(name: str):
    hello = "hello " + name
    return hello
names = [
    "suzuki",
    "yamada",
    "tanaka",
]
hello_names = [get_hello(n) for n in names]

print(hello_names)

VSCode上で、こんな感じに型アノテーションを自動で補完してくれます。

引数など最低限は書く必要はありますが、かなり楽にちょっと見栄えの良い型アノテーション付きのコードにすることができます。

補足

Pythonでも型を書けと書きましたが、型アノテーションはあくまでアノテーション。つまり注釈です。型を書いてもPythonは静的型付け言語になるわけではなく、動的型付け言語であることには変わりありません。
ですので、個人的には型アノテーションは必要以上に厳密に書く必要は無いと思っています。厳密にやりすぎると、コーディングが複雑になったりコード量が増えたりして、逆に人が読みづらくなったりすることもありますので。
そういう思いもあり、この章のタイトルに引数と戻り値にはをつけました。
（でも基本は書いたほうが見やすくなるので、複雑になりすぎない範囲でできるだけ全変数に書きましょう）

最後に

pythonは、データ分析や機械学習の分野で幅広く使われています。
そういった分野だと、複数人で1つのアプリケーションを開発する場合と比べて、1人が何度も実際に動かして確認するケースが多いかと思います。そのこと自体は問題ないのですが、「アプリ化してくれ」と他の人に依頼するのであれば、単純に正しく動くだけのコードではなく相手が扱いやすいコードを意識したほうがより良くなるかと思います。

本当は他にもいろいろ言いたいことはあるのですが、せめてこのくらいは頼むよという感じです。。。

以上です！！！