書くだけじゃダメ、利用者のことまで考えた docstring の書き方の提案。

はじめに

docstringの使い方を思いついたので備忘録

本文

下記のような縦横のpxのサイズがあります。

large  = [512, 512]
medium = [256, 512]
small  = [256, 256]

これをプロジェクト共通のサイズとして、色々なファイルで使うことになりました。

なので、下記のような Sizeクラス として適宜importして使うことにしました。

# Size.py
class Size:
    large  = [512, 512]
    medium = [256, 512]
    small  = [256, 256]

そして、クラスの説明として、下記のようなdocstringを書きました。

# Size.py
class Size:
    """
    共通して使うサイズ
    * large
    * medium
    * small
    """
    large  = [512, 512]
    medium = [256, 512]
    small  = [256, 256]

こうすることによって写真のような説明がされます。

しかし!!
large,medium,smallがそれぞれ何pxなのかがわかりません...

下記のようにすればいいと思った方がいるかもしれません。

# Size.py
class Size:
    """
    共通して使うサイズ
    * large [512, 512]
    * medium [256, 512]
    * small [256, 256]
    """
    large  = [512, 512]
    medium = [256, 512]
    small  = [256, 256]

問題

これだと問題があります。それは...
下記のような時、largeのpxを見るためにSizeをホバーしなければいけないんです。

from Size import Size
print(Size.large)

それにlargeのpxだけ知りたいのに、他の邪魔な情報も出てきてしまいます。

解決策

そこで、今回思いついたのが、メソッド化するということです。

class Size:
    """
    共通して使うサイズ
    """
    def large():
        """
        [512l, 512]
        用途 : 大アイコン
        """
        return [512, 512]

        
    def medium():
        """
        [256, 512]
        用途 : バナー
        """
        return [256, 512]

        
    def small():
        """
        [256, 256]
        用途 : 小アイコン
        """
        return [256, 256]

上記のようにメソッド化することによって、
それぞれ細かく説明でき、かつ必要な情報だけを見ることができるようになりました。

おわり

チーム開発を進めるときは、自分が作ったclassをどのように使われるか、
それを意識して開発すると良いと思います。