Pythonを学んでいると「docstring（ドックストリング）」という言葉を目にすることがあります。これは関数やクラスの説明を記述するための仕組みで、コードの可読性を大きく向上させます。本記事では、Pythonのdocstringの書き方から応用例までわかりやすく解説します。
docstringとは？
docstringとは、Pythonにおける「ドキュメント文字列」のことを指します。関数やクラス、モジュールの直下に記述し、その役割や使い方を明示するために利用します。これにより、コードを読む人が処理内容を理解しやすくなるだけでなく、自動生成されるドキュメントにも活用されます。特にチーム開発や大規模なプロジェクトでは、docstringの有無が作業効率に大きな差を生み出します。
Pythonでのdocstringの基本的な書き方
docstringは三重引用符（””” または ”’）で囲んで記述します。例えば関数の直下に記述することで、その関数の説明文を定義できます。次の例を見てみましょう。
def greet(name):
"""名前を受け取り、挨拶文を返す関数
Args:
name (str): 挨拶する相手の名前
Returns:
str: 挨拶文
"""
return f"こんにちは、{name}さん！"
このようにdocstringを加えることで、関数の役割や引数の型、戻り値を簡単に理解できるようになります。
docstringを確認する方法
docstringは、Pythonの組み込み関数help()や、.__doc__属性を利用して確認できます。これにより、コードを読まなくても関数やクラスの使い方を素早く把握できます。
print(greet.__doc__)
help(greet)
これらを実行すると、先ほど記述したdocstringが出力されます。とても便利な機能で、特に外部ライブラリを使う際にも役立ちます。
docstringの書き方のスタイル
docstringにはいくつかの記法スタイルがあります。代表的なのは以下の3つです。
Googleスタイル
def add(a, b):
"""2つの数値を加算する
Args:
a (int): 加算する数値
b (int): 加算する数値
Returns:
int: 計算結果
"""
return a + b
NumPyスタイル
def multiply(a, b):
"""2つの数値を掛け算する
Parameters
----------
a : int
掛け算する数値
b : int
掛け算する数値
Returns
-------
int
計算結果
"""
return a * b
reStructuredTextスタイル
def divide(a, b):
"""2つの数値を割り算する
:param a: 割られる数値
:type a: int
:param b: 割る数値
:type b: int
:return: 計算結果
:rtype: float
"""
return a / b
どのスタイルを使うかはプロジェクトやチームのルールに合わせるのが一般的です。
応用テクニック：docstringを活用したドキュメント生成
docstringはただの説明文としてだけでなく、自動ドキュメント生成ツールと組み合わせて使うことも可能です。例えば、Sphinxを利用すると、docstringをもとにHTML形式のドキュメントを自動生成できます。これにより、開発者が追加の作業をせずとも統一感のあるドキュメントを整備できます。特にライブラリやAPIの開発では大きな効果を発揮します。
よくあるエラーと注意点
docstringを書く際には以下のような注意点があります。
- 省略しないこと：関数が単純でも、説明を省略すると理解が難しくなります。
- 内容が古くなること：コードを変更した際にdocstringを更新し忘れると、誤った情報を伝える原因になります。
- スタイルの統一：複数人で開発する場合はスタイルを統一することで、可読性が大きく向上します。
このようなポイントを意識しておくと、docstringを効果的に活用できます。
Python初心者におすすめのサービス
「もっと実践的なコード例が欲しい」「自分の用途に合わせて教えてほしい」という方には、
テックアカデミーがおすすめです。
AI関連コースやシステム開発コース、アプリ開発コースなど豊富な学習が可能です。
さらに今なら無料相談でアマギフプレゼントもあるので、気軽にお申込みしてみてください。
また、プログラミング学習のプラットフォームとして、ココナラでは、現役エンジニアや経験豊富なPython講師が、あなたのレベルや目的に合わせてマンツーマンで指導してくれます。
書籍や動画ではカバーしきれない、あなた専用のカリキュラムで学べるのが最大の魅力。短時間で効率的にスキルを伸ばしたいなら、まずは出品者のサービスをチェックしてみましょう。
また、教える側としてスキルを活かして副業・独立を目指すことも可能です。
プログラミング経験やPythonの知識があれば、自分の得意分野をサービスとして出品し、全国の学習者から直接依頼を受けられます。オンラインで完結するため、場所や時間に縛られず、自分のペースで働けるのも大きなメリットです。
こちらのリンクから詳細をチェックしてみてください。
まとめ
Pythonのdocstringは、コードの理解を助ける重要な要素です。適切な書き方を学び、プロジェクトに合わせたスタイルを選ぶことで、開発効率や可読性が飛躍的に向上します。
参考リンク
以下のリンクから、
SESの組込みシステムから色々な不満を持ち、自社WEBサービスへ転職した実体験の記事がありますので、是非読んでみてください。とても喜びます。
SESの組込みシステムから自社WEBサービスのエンジニアに転職した話
コメント