コメントとdocstring

コードは一度書いて終わりではなく，後から自分や他者が読み返すもの． ここでは，コードを説明する基本として，コメント・docstring・ヘルプの読み方をまとめる．

コメント # を見直す¶

# から行末まではコメント (comment)で，実行時には無視される． コメントは「何をしているか（what）」をなぞるよりも，「なぜそうするか（why）」を書くと価値が高い． コードを読めばわかることの繰り返しは避ける．

t = 9
t_max = 10

# 悪い例：コードを読めばわかる what をなぞっている
t = t + 1  # t に 1 を足す

# 良い例：なぜそうするか（why）を書く
if t >= t_max:  # 最終世代に達したらシミュレーションを止める
    print("終了")

終了

本演習では，コメントは日本語で書き，スライドと対応するコードには # XX-YY. タイトル の番号を付ける慣例．

docstring を書く¶

docstringは，関数などの先頭に置く説明用の文字列である．def の直後に """...""" で書く．

def add(a, b):
    """2つの数の和を返す関数．"""
    return a + b

引数や戻り値が複数あるときは，書式を決めて節ごとに整理すると読みやすい． Google スタイル（Args:・Returns:）と NumPy スタイル（Parameters・Returns）が代表的 napoleon 拡張．

下の例は Google スタイル．

import numpy as np


def log_spiral(a, r0, theta):
    """対数らせんの座標値を返す関数．

    Args:
        a: らせんの拡大率
        r0: 動径の初期値
        theta: 回転角

    Returns:
        x, y: らせん上の座標値

    """
    r = r0 * np.exp(a * theta)
    x = r * np.cos(theta)
    y = r * np.sin(theta)

    return (x, y)

同じ関数を NumPy スタイルで書くと次のようになる．

def log_spiral(a, r0, theta):
    """対数らせんの座標値を返す関数．

    Parameters
    ----------
    a : float
        らせんの拡大率
    r0 : float
        動径の初期値
    theta : float or ndarray
        回転角

    Returns
    -------
    x, y : float or ndarray
        らせん上の座標値
    """
    r = r0 * np.exp(a * theta)
    x = r * np.cos(theta)
    y = r * np.sin(theta)

    return (x, y)

これは P2-01 の対数らせんモデルで実際に使う関数． docstring を書いておくと，自作関数も「使い方が説明された部品」になる．

docstring・ヘルプを読む¶

書いた docstring は，あとから呼び出して読める． 標準ライブラリ・NumPy・自作関数のいずれも同じ仕組みで，未知の関数に出会ったらまずヘルプを読む，というのが調べ方の基本．

Colab/Jupyter では次の方法が使える．

• 関数名?（例：np.cos?）：docstring を別画面に表示する

• Shift+Tab：入力中の関数のシグネチャと docstring をその場に表示する

• help(関数名)：どの環境でも使える標準的な方法

help(log_spiral)

Help on function log_spiral in module __main__:

log_spiral(a, r0, theta)
    対数らせんの座標値を返す関数．
    
    Args:
        a: らせんの拡大率
        r0: 動径の初期値
        theta: 回転角
    
    Returns:
        x, y: らせん上の座標値

書く（docstring）と読む（ヘルプ）は表裏の関係にあり，自分が書いた docstring も他人が書いたものとまったく同じように読める．

自動化¶

Sphinx の napoleon 拡張が解釈し，docstring からドキュメントを自動生成できる．

コメントや docstring を含め，コードの体裁を一定に保つにはリンタ・フォーマッタが役立つ． 本リポジトリでは Ruff を用い，整形（ruff format）と検査（ruff check）を自動化している． 関数の引数や戻り値の型をコードに明記する型ヒントなどもある．

まとめ¶

• コメント：なぜ（why）を簡潔に補う

• docstring：自作関数の使い方を残す

• ヘルプを読む：help() や ? で未知の関数を自力で調べる