コードスタイルガイド¶

このガイドには、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固有の追加事項もいくつかあります：

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

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

my_function(
    arg1, arg2, arg3
)

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

my_function(
    arg1,
    arg2,
    arg3,
)

長い文字列の分割¶

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

my_function(
    (
        "this is a very long string "
        "that is wrapped over two lines"
    ),
    second_argument,
)

以上：

my_function(
    "this is a very long string "
    "that is wrapped over two lines",
    second_argument,
)

避けるべきこと¶

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

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