コードスタイルガイド¶

このガイドには、BeeWare のコードを書くための情報とガイドラインが含まれています。

コーディングスタイル¶

BeeWareのコードベースではPEP 8に準拠していますが、行長は79文字から88文字に拡張されています。可能な限りRuffを使用してPEP 8の規約を強制します。コードをコミットする際、pre-commitがRuffを含むチェックを実行します。可能な場合、これによりコードが自動整形され、当社のフォーマットおよびスタイル基準を満たすことが保証されます。一部のIDEでは保存時にRuffを自動実行するよう設定でき、このプロセスを支援できます。

PEP 8で最も重要な部分はセクション0: 愚かな一貫性は小物の悪霊であるであることを心に留めておいてください。PEP 8との一貫性を保つことが意味をなさない状況も存在し、適用可能な場合には、記載された規則に沿わないコードを書くことが許容され、時には望ましい場合もあることを理解することが重要です。それらのルールにいつ不整合を許容すべきかを知ることは、ほとんどの状況で一貫性を保つことと同じくらい重要です。

この傾向は、命名規則にも表れています。BeeWareライブラリは、他の言語との橋渡しを必要とすることがよくあります。他の言語向けのラッパーを構築する際には、Pythonの命名規則ではなく、対象言語の命名規則に従うことが望ましい（場合によっては必須）です。例えば、Javaコードを呼び出したり参照したりする場合、関数名はPEP 8で推奨されているmixedCaseではなく、Javaで推奨されているsnake_caseに従うべきです。

APIの命名規則、変数名などについては米国式スペルを採用します。

また、PEP 8にはBeeWare固有の追加事項もいくつかあります：

PEP 484 に準拠した型注釈は任意ですが、特に公開APIのインターフェースにおいては、引き続き強く推奨されます。

適切な型ヒントとSphinxドキュメント文字列を含む標準関数の定義例を以下に示します：

def function_name(param1: int, param2: str) -> bool:
"""型とdocstringを指定した関数の例。

:param param1: 最初の引数。
:param param2: 2番目の引数。

:returns: 戻り値。成功した場合はTrue、それ以外はFalse。
"""

長い関数呼び出しの分割¶

引数が複数ある関数呼び出しが1行に収まらない場合は、各引数をそれぞれ別の行に配置し、最後の引数の後にコンマを付けます。Ruffでは、改行を挟んで1行に複数の引数を並べる形式も許可されており（また、その形式を推奨します）：

my_function(
    arg1, arg2, arg3
)

この書き方は避けてください。代わりに、最後の引数の後にコンマを付け、引数を1行に1つずつ配置してください：

my_function(
    arg1,
    arg2,
    arg3,
)

長い文字列の分割¶

文字列引数を、行の長さの制限を満たすために複数行に分割する必要がある場合は、連結された文字列リテラルを括弧で囲み、その文字列が単一の引数であることを明確にしてください。つまり、次のような記述を推奨します：

my_function(
    (
 "これは非常に長い文字列です"
 "2行にまたがって表示されています"
    ),
    second_argument,
)

以上：

my_function(
    "これは非常に長い文字列です "
    "2行にまたがって表示されています",
    second_argument,
)

避けるべきこと¶

可能な限りutilsモジュールは避けるように努めていますが、場合によっては避けられないこともあると認識しています。望ましい代替策は、utilsモジュールを使用する代わりに、ソースコード内の別の場所でその機能を実現できる箇所を見つけることです。

一般的なルールとして、アプリの起動を高速化するため、高コストな初期化コードは回避または遅延させるよう努めています。例えば、toga-coreパッケージのモジュールは「遅延読み込み」されており、最初から全て読み込まれるのではなく、要求された時点で初めてインポートされます。これにより起動が高速化され、アプリが実際に使用している部分のみに時間を費やすことができます。

コメントを書く際は、「we」などの一人称複数代名詞の使用を避けてください（例えば、「We loop over」ではなく「Loop over」と記述してください）。

テストのdocstringでは、各テストが実証する期待される動作を記述してください。「～をテストする」や「～であることを確認する」といった前置きは含めないでください。

ドキュメントの記述やコメントでは簡単に説明しきれない詳細情報が記載されている、あまり知られていない問題については、チケットの参照情報を記載してください。次のように、文の最後にチケット番号を記載してください：

def test_foo():
 """テスト用のdocstringは次のようなものです (#123456)。"""