Style.md

本の構造

最終更新日: 2024/2/25 原文: https://github.com/apple/swift-book/blob/main/Style.md

TSPL は 3 つの主なパートに加えて、補完的な機能を提供するいくつかの序文に分かれています。

Swift ツアー(一般的に「ツアー」と呼ばれる)では、興味深い Swift コードがたくさん表示されますが、言語がどのように機能するかについてはほとんど何も触れていません。例えば、ガイド(後述)にはオプショナルチェーンに関する章がありますが、ツアーでは数文に要約されています。ツアー内では、構文とその使用方法を理解するだけで十分です。オプショナルチェーンがどのように機能し、いつ使用する必要があるのかについての実際の詳細な説明は、ガイドに任せています。

ツアーの意図は、一度に全体を読むことができることです。初心者は、Swift でできることの概要を理解できます。プログラミングの経験が豊富な読者は、「Swift が危険である」と知ることができます。つまり、最初のプロジェクトで混乱し始めるのに十分な Swift の言語構文を使用し、他の言語から既に知っている概念について、表面レベルの Swift の言語構文以上の内容について学ぶ準備ができたら、TSPL に戻ってきます。

言語ガイド(一般的に「ガイド」と呼ばれる)は、学習するのに役立つ順序で Swift 言語について案内します。ただし、言語または Swift 標準ライブラリのすべての機能を紹介することを約束するものではなく、いくつかのより複雑な基礎となる内容について、正確な詳細を端折って説明します。このガイドは、リファレンス(後述)に基づいて、核心を突いた詳細な疑問を解決し、言語を徹底的にカバーしています。リファレンスとは異なり、言語機能の実際の例を示しながら、順を追って説明します。事前の知識はほとんど必要ありません。

ガイドに新しいセクションを追加するときに、上から順番に読むことができるという決まりを維持するためには、説明で使用するすべての構文と概念が事前の章で既に説明されていることを確認してください。「基本」の章は、主に、ガイド内の最初の方の章で必要な一連の構文と概念を紹介するために存在します。「基本」の多くのトピックは、ガイドの後半でさらに詳しく説明されています。

このガイドには、2 つの理由から Swift 標準ライブラリの型が含まれています。それは、言語の概念を説明するために必要であるということと、あまりにも一般的であるため、読者がそれらなしでは役に立つものを構築できないということです。後者の理由には、個人的意見が含まれます。Swift 標準ライブラリに新しい型が導入されると、通常、それらを TSPL に追加するかどうか、どこに追加するかについて話し合う必要があります。

このガイドは、基本的なトピック、データモデリングのトピック、高度なトピックの 3 つの主要なまとまりに分けることができます。基本的なトピックの範囲は、列挙型、構造体、クラスの前のすべてのトピックです。高度なトピックの範囲は、デイニシャライゼーションの後のすべてのトピックです。データモデリングはその中間の内容です。これらの主要なまとまり間でしばらく読むのをやめてしまったとしても、上から順番に読めば、そのまとまりの意味がわかるように意図して作成されています。例えば、基本的なトピックを読むだけでも、構造化されていない「プリミティブ」なデータのみを持つプログラムを作成するのに十分な情報が得られます。各まとまり内は、最初に基本的なトピックが配置され、ほとんどの読者がスキップできるトピックが最後に配置されています。

言語リファレンス(一般的に「リファレンス」と呼ばれる)は、Swift 言語のすべての側面を完全に詳細に説明していますが、教科書になることを意図したものではありません。これは、形式文法の形に従って並べられており、例と応用を端折っています。いくつかの場所では、例を示したガイドへのリンクを明示しています。リファレンスは、初心者に親しみやすいものである必要はありませんが(これはガイドが対応しています)、言語の中でもめったに深掘りされない領域にも焦点を当てて、正確かつ明確である必要があります。そのためには、取っつきやすさや親しみやすさを犠牲にしなければならない場合があります。多くの読者はこういった領域のリファレンスすら必要としないので大丈夫ですが、リファレンスが不明確だと、答えが必要な読者は他に行く当てがなくなってしまうからです。

リファレンス内は、セクションの内容が推測できるような 4 部構成になっています。

• 見出しの言語構造を 2、3 文で簡単に説明します
• コードの概要はその一般的な構文の形を示しています
• 2、3 段落でより詳細を説明します
• 文法は構文を形式的に記述します

形式文法の目的は、リファレンスのシンプルな文では完全に答えられなかった問いに対して、(意味についてコメントすることなく) Swift として妥当な形式は何かという問いに明確に答えられるようにすることです。これは主に人間の読者を対象としているため、Swift コードのパーサーを生成するのに常に適しているとは限りません。

用語とルール

属性名

ガイドでは、属性名の前に @ を書きます。 リファレンスでは、省略します。

back deploy

2 つの単語でつづり、1 単語にしたり、ハイフンを付けません。

deprecation

言語リファレンスの非推奨の機能を説明するセクションの冒頭に、非推奨の注釈を追加してください。以下のような表現とマークアップを使用してください:

> 非推奨:  
> この属性は非推奨です。  
> [main](./language-reference/attributes.md#main)を代わりに使用してください。  
> Swift6では、この属性を使用するとエラーになります。

definite initialization

"definitive initialization"ではありません。 DI という略称を使ってはいけません。

コンパイラ

下記の Swift の項目を見てください。

関数

リファレンスでは、「関数」にフリー関数とメンバー関数の両方が含まれるため、メソッドについても個別に言及しません。ガイドでは、「関数とメソッド」と書いています。

見出し

見出しにはアンダーラインではなく番号記号(#)を使用します。

4 階層の見出しは許可されており、本でも使用されていますが、通常は避けるようにしてください。深くネストした見出しは、多くの場合、コンテンツを整理するためのより良い方法があることを示しています。

memberwise initializer

"member-wise"のようにハイフンをつけないでください。

マクロ名

ガイドでは付属マクロ(attached macros)を指す場合は名前の前に @ を、自立式マクロ(freestanding macros)を指す場合は名前の前に # を記述します。 リファレンスでは、省略します。

メソッド

「関数」の項目を見てください。

non-optional

nono-ptional と誤読を避けるためにハイフンでつなげます。Apple スタイルガイドのハイフンの通常のルールでは、ハイフンは省略されます。

コミット(51c4fbc135a5e82343a0f5d9121f8a060b59f1a3) および rdar://problem/44881846 も参照してください。

非同期ではない

二重否定の代わりに「同期」を使用してください。

オペレーター

初めて名前付き演算子を導入するときは、その名前の後にその記号を付けます。以降の使用では、シンボルを単独で使用してください。例えば:

デフォルトでは、独自のクラスと構造体には、等号演算子(==)または不等号演算子(!=)の実装がありません。通常は == 演算子を実装し、== 演算子の結果を否定する != 演算子はSwift 標準ライブラリのデフォルト実装を使用します。== 演算子を実装するには 2 つの方法があります。

オペレーターに確立された英語の名前がない場合は、発明した名前についてテックレビューを受けるようにしてください。

オプショナルバインディング

冠詞を省略してください。"use an optional binding"ではなく、"use optional binding"を使用してください。

受動態

一般的に、能動態はより読みやすい傾向があるため、能動態で文を書くことができるときに受動態を避ける、という書き方のガイダンスは引き続き適用されます。ただし、TSPL の主題によっては、あいまいなコンパイラや Swift やパーサによって実行されるため、能動態にしても意味のある主題がない場合もあります。その場合、動作主ではなくアクションに焦点を当てた文を書くには、受動態がより明確です。

例えば、「X は Y として理解される」というフレーズは、構文の意味を説明する際にリファレンスに何度か登場します。この場合、理解を実行する明確な動作主が存在せず、その動作主がわからないであるため、受動態は能動態よりも明確です。

潜在的な中断点(potential suspension point)

これは、await のセマンティクスを説明する際に推奨される表現です。文脈上指しているものがすでに明確であり、繰り返しの「潜在的な」が冗長になる場合は、単に「中断点」に短縮できます。

コードリストの前の句読点

コードリストが基本的に文の一部のように機能し、リストでは通常の文がそれを明示的に参照している場合、「次のように」または「以下に示すように」のようなフレーズで終わる文の後にコロンを書きます。「例えば:」のように文の断片の後にコロンを使用します。コードについて述べている文の後にはピリオドを書きますが、コードを参照する単語は含めません。「次のコードでは」のような語句で始まる文には読点を使用します。

注意: この用法は既存のテキストと完全に一致しているわけではありません。これについてコミッティグループと話し合う必要があります。

runtime, run time

Apple スタイルガイドでは、コードの実行時点(run time)とコードの実行環境(runtime)の両方に「runtime」を使用します。これまでのところ、Obj-C の実行環境がドキュメント化されているように Swift の実行環境はドキュメント化されていないため、この区別を行う必要はありませんでした。(Swift の実行環境は、Obj-C の実行環境のように API を公開していないため、私たちは、一部ドキュメント化していません) 一般的に、用語の使用方法が異なるため、例外を除いて文脈から違いは明らかです。「run-time error」や「runtime error」などのフレーズは、コードの実行中に発生するエラーと、Swift の実行環境に起因または関連するエラーをそれぞれ指します。

共有可変状態

アクターを説明するときはこの単語を避けてください。設計上、アクターは可変状態を共有することを具体的に避けています。可変状態は非公開であり、アクターの(async)メソッドを介してのみアクセスできます。

標準ライブラリ(standard library)

最初の使用では、「Swift 標準ライブラリ」と完全に明記してください。 文脈上がすでに明確で完全な名前を繰り返すのがくどい場合、「標準ライブラリ」と短縮できます。 (現在、そういった例はありません)。

生成(spawn), 開始(start)

API のシンボル名と一致するように、代わりに「追加(add)」で新しい Task の作成について言及してください。(生成や開始という名前は、以前のバージョンのプロポーザルで使用されていました)

中断点(suspension point)

潜在的な中断点の項目を見てください。

構文のアウトライン

統語構造(コードがどのような構造をしているのか)の形状を示す場合にのみ使用してください。構文のアウトラインの後に続く本文のプレースホルダ(いわゆる、青いバブル)を参照する場合は、その名前をイタリック体にします。

構文ののアウトラインは、ガイドでは控えめに使用されていますが、リファレンスでは広範囲に使用されています。

Swift

このガイドでは、コンパイラまたは言語が行っていることを説明するときに、Swift を「親しみやすい」主題として使用しています。例えば:

Swift は、現在のインスタンスのプロパティまたはメソッドを参照していると想定します。

Swift は someString 定数を String 型と推測することに注意してください。

Any 型の値が期待される場合にオプショナル値を使用すると、Swift は警告を表示します。

リファレンスでは、コンパイラがアクションを実行する実際の動作主である場合に具体的に言及しています。私たちはパーサ(parser)、レキサ(lexer)、オプティマイザ(optimizer)などのコンパイラの詳細を区別しません。

トーン

一般的に、そして特にガイドは、楽しさが伝わるように書くべきです。本書内の例は簡単で、読みやすいものでなければなりません。つまり、現実的なコードが好まれ、多くの章で複数の例に共通の物語が織り込まれています。その連続した物語のつながりは、後々の変更をより大変にする可能性がありますが、章の流れが良くなり、全体としてよりよくまとまるため、総じて十分にそうする価値はあると思います。

読みやすさと親しみやすさのために、たとえリファレンスであっても、構文を説明しているだけであっても、1 文字または無意味な識別子を持つ例は記述しません。関連がない場合は、代わりに SomeStructure などの型や someArray などの変数を使用します。

私たちの例の中には、ガイドツアーのホタルの乗組員についてのジョークなど、本の外のものへのユーモラスな言及が含​​まれています。いくつかには、それらを解説している REFERENCE コメントが付いています。そういった言及の意味がわからなかったとしても、何事もないように全部無視できます。また、言及があることに気づいたけれどもジョークを理解できなかった場合は、オンラインで簡単に検索できるはずです。

ガイド内のコードリストは、通常、3 部構成の法則に従います。コードリストの前の段落では、解決しようとしている問題を組み立て、次にコードが何をするかを非常に高いレベルで説明しています。コードの後のパラグラフ(場合によっては複数のパラグラフ)では、コードリストが何を行ったかを詳しく説明します。この意図は、本質的に段階的な開示を提供することです。上級の読者はコードリストの後の段落をスキップでき、その前のテキストの一部でさえもスキップできるかもしれませんが、必要な読者には、コードは完全に前提知識なしでも理解できるように説明を提供しています。

ツアー、ガイド、リファレンスのバランスについては、このリポジトリのトップの階層にある README ファイルを参照してください。

意味のある改行(Semantic Line Breaks)

このリポジトリのマークダウンファイルでは、文や句の区切りとなる行末に改行を使用します。こうすることで、プルリクエスト、コミット通知メール、およびターミナルなどの場所で表示されたときに、差分が読みやすくなるよう行を十分に短く保つことができます。行は意味のある場所で改行されるため、段落全体を再改行するような変更は必要はなく、変更された行のみがマークされるようになります。これにより、git-blame などのツールで行ごとの履歴を取得できます。

執筆時は、行を 80 文字以下にすることを目指して書いてください。各文の後、および必要に応じて句の境界で新しい行を開始しましょう。長いリストの場合、各リストアイテムをそれぞれの行に配置する場合もあります。これは、行を並べ替えることができるため、アルファベット順に並べたいリストで最も役に立ちます。本書にはいくつかの異なるスタイルがあるので、特定のアプローチに厳密に従う必要はありません。

既存のテキストを編集するときは、可能であれば改行を保持して、差分を小さく保ち、行ごとの履歴を保持できるようにします。実際に他の変更を加えていない限り、長すぎるという理由だけで既存の行を折り返さないでください。歴史的な理由から、本には 90、 100 文字の行の長さを使用する部分があります。行の長さだけのためにそれらを再改行すると、履歴を追跡するのが難しくなり、ノイズの多い差分が作成されます。

歴史的なメモとして、1974 年の Brian W. Kernighan による「UNIX for Beginners」がおそらくこのアプローチの起源でしょう。11 ページには、「ドキュメントを準備するためのヒント」セクションに次のガイダンスがあります:

ほとんどのドキュメントは、最終的に完成するまでに(常に予想以上に)複数のバージョンを経ます。したがって、それらを簡単に変更できるように、できる限りのことを行う必要があります。

まず、入力というただ機械的な操作を行う場合は、その後の編集が容易になるように入力します。各文は新しい行で開始します。行を短くし、コンマやセミコロンの後など、ランダムにではなく自然な場所で改行します。ほとんどの人は、フレーズを書き直したり、文を追加、削除、並べ替えたりしてドキュメントを変更するため、こういった予防措置により、後で行う必要のある編集が簡単になります。

このガイダンスは、もともと紙のテレタイプでラインエディタの ed(1) を使用して nroff および troff ファイルを用意するという文脈で書かれていましたが、Git やその他のプログラミングツールは一般的にテキストが 80 文字未満の行で構成されることを期待しています。

形式文法

これらのガイドラインは、リファレンスの「Grammar of X」ブロックに適用されます。

**ASCII 矢印を書きましょう。**矢印(-->)は「で構成できる」と読むことができます。

RST(※)で矢印を作成するには、2 つのハイフン(-)の後に右山かっこ(>)を使用します。本では、すばらしい Unicode 矢印にレンダリングされます。

※ ReStructuredText: https://www.sphinx-doc.org/ja/master/usage/restructuredtext/basics.html

バッククォートを 2 つ使用してリテラルを記述します。 例えば:

forty-two --> ``42``

追加のマークアップなしで構文カテゴリ名を記述しましょう。 構文文法ブロック内では、自動的に斜体で表示されます。それらの上にある英語の通常の文からそれらを参照しないでください。

**構文カテゴリの名前として完全な英単語を使用しましょう。**スペースの関係で、これが実現できない場合があります。例えば、C スタイルの for 文の文法では、for 文の初期化部分で定義するカテゴリを for-init に短縮する必要がありました(規則で指定されているようなfor-initialization ではなく)。この場合、読みやすさや教育上の観点から見れば、何も失われていないと考えられます。

c-style-for-statement --> ``for`` for-init-OPT ``;`` expression-OPT ``;`` basic-expression-OPT brace-item-list
c-style-for-statement --> ``for`` ``(`` for-init-OPT ``;`` expression-OPT ``;`` basic-expression-OPT ``)`` brace-item-list

for-init --> variable-declaration | expression

**代替案を示すには、パイプ(|)を使用しましょう。**選択肢が多すぎて 1 行に収まらない場合は、選択肢ごとに新しい行を使用します。パイプと改行を混ぜないでください。

例えば、case-block-item は宣言、式、または文で構成できることを指定するために、改行の代わりにパイプを使用できます。これは、3 つの選択肢すべてを 1 行にうまく収めるためです。

code-block-item --> declaration | expression | statement

パイプを使用する場合は、読みやすくするために、各選択肢の項目数を少なくしてください。最も一般的なケースは、各選択肢が単一のリテラルまたは単一の構文カテゴリのいずれかである場合ですが、常に可能であるとは限りません。

一方、制御転送文の文法を考えてみましょう:

control-transfer-statement --> break-statement
control-transfer-statement --> continue-statement
control-transfer-statement --> fallthrough-statement
control-transfer-statement --> return-statement

control-transfer-statement --> break-statement
control-transfer-statement --> continue-statement
control-transfer-statement --> fallthrough-statement
control-transfer-statement --> return-statement

パイプを使用して各代替案を分離するには、単一の行だと余裕がない場合があります。次のようなものは見栄えがよくない傾向があります:

control-transfer-statement --> break-statement | continue-statement | fallthrough-statement | return-statement

オプションであることを示すために -OPT を追加しましょう。 構文文法ブロック内では、これは添字「opt」に自動的に変換されます。

繰り返しには複数形を使用しましょう。 BNF(※) では、これはプラス(+)または星(*)で表されます。正式な文法の構文には繰り返し演算子が含まれていないため、2 つの構文カテゴリを使用して繰り返しを表します。 例えば:

categories --> category categories-OPT
category --> More formal grammar goes here.

switch-statement --> ``switch`` basic-expression { switch-cases-OPT }
switch-cases --> switch-case switch-cases-OPT
switch-case --> case-label statements
switch-case --> default-label statements
switch-case --> conditional-switch-case

※ バッカス・ナウア記法 https://ja.wikipedia.org/wiki/バッカス・ナウア記法

複数形は、単数形のものを繰り返しリストのみで構成されます。カンマなどの区切り文字が必要な場合は、「list」と呼びます。

case-label --> attributes-OPT ``case`` case-item-list ``:``
case-item-list --> pattern where-clause-OPT | pattern where-clause-OPT ``,`` case-item-list

上に示したように、繰り返しを扱うときは右再帰を使用します。

**グループ化括弧を省略しましょう。**私たちの形式文法では、グループ化括弧を使用しません。-OPT を使用したオプションは常に、直前の 1 つのトークンのみに適用され、| を使用した 1 つの代替案のみに適用されます。または改行が許可されます。

括弧を使用する新しい言語機能の BNF 文法が現れた場合は、それらを削除する際に創造性と判断力を働かせる必要があります。

例えば、BNF ルールのこの部分を翻訳するには、新しいカテゴリを考え出す必要があり、定義する必要がありました:

('where' expr)?

これは:

guard-expression-OPT
guard-expression --> ``where`` expression

になります。

この BNF ルールは少し複雑で、上記のルールのいくつかを適用する必要がありました:

stmt-switch-case ::= (case-label+ | default-label) brace-item*

これは:

switch-case --> case-labels brace-items-OPT | default-label brace-items-OPT

になります。