表記の統一

[azu]

書籍の用語の表記のぶれや説明の仕方にぶれがあるので、出来るだけ統一した書き方をする。

• [x] Promise

❌ Promises

Promiseという機能について言う時は大文字の単数を使う。

例外としてES6 Promisesの仕様へのリンクを貼る時はsをつけてもよい。

小文字は基本的にpromiseオブジェクトのみにする。

related #7

• [x] thenで登録するコールバック関数

thenで渡すコールバック関数の事

thenで登録するコールバック関数 という書き方を大体してるが、他の書き方の方が分かりやすいかどうか？

thenに登録するハンドラ？

thenで登録されたコールバック関数

という表記にする。

• [x] FulFilled または Rejected

いわゆるSettledの状態になった時という意味。 短縮しないで、毎回両方の状態について書いてる。

解決された時という書き方だと誤解を生みそうだし、Settledという言葉は馴染みがないので毎回書いてるが、より良い表現はないかどうか？

resolve または reject された時 という表現も使ってる。

どちらが主語になってるかの違いだけどどう統一しよう。

---

迷いそうな表記はCONTRIBUTIONファイルか何処かにまとめておく。

[azu]

章、セクション

セクションって言葉は途中から使い始めた気がする。 どこかで混ざってそう

[azu]

事、こと

結構混ざってる感あるというか、IME的に統一して書くの難しい

[azu]

FulFilled または Rejected

:bulb: この用語の混乱する原因は

Promiseコンストラクタで(executor functionである)resolveが呼ばれた -> (promiseオブジェクトが)Fulfilledとなった -> onFulfilledが呼ばれる

という対象が途中で変わってる所にあるから、最初の説明にこの流れ自体をちゃんと書いてあげるのがいいと思う。

[azu]

主語がPromiseの場合はresolve and reject (Promiseがresolveした時)

主語がpromiseオブジェクトの場合はFulfilled and Rejected. (promiseオブジェクトがFulfilledとなった時)

---

後、resolve(解決) と reject(棄却)としてるけど、 素直に成功と失敗に統一した方が直感的な気がする。

[azu]

resolve,reject / FulFilled,Rejected の表現

方針を決めたのでメモる(CONTRIBUTE.mdに入れておくべきかな)

resolve と reject の注釈

• それぞれの用語の日本語の対応は resolve = 成功時 、 reject = 失敗時 とする。
• resolveした時 ≠ 解決した時 としない(解決という言葉紛らわしいので避けるべき)

promiseオブジェクトが主語の場合

• "promiseオブジェクトがFulFilled または Rejectedとなった時" と表記する
• 必ず大文字で FulFilled とする

resolve,reject / FulFilled,Rejected の使い分け

• "処理が成功した時" or "処理が失敗した時" という表現を使う場合、曖昧さが残らないように気をつける
  • 例えば、"処理が成功した場合はonFulfilledが呼ばれますが" というようにその結果についても触れる
• new Promise の処理について述べるなら、"resolveした時" と書いてもよい。
  • "resolveされた時" とは書かない
• thenでのメソッドチェーン等、new Promiseと直接関係ないケースの場合にはFulFilled,Rejectedを使う

例) Promise.raceは、promiseオブジェクトがどれか一つでもFulFilled または Rejectedになったら次の処理を実行します。

[azu]

https://github.com/azu/promises-book/blob/master/CONTRIBUTE.md

に表現についてを追加した。

[azu]

利用者、ユーザー

利用者 - ライブラリの利用者という感じで使う。 ユーザーよりも利用者の方がイメージがつきやすいので、利用者を優先する

[azu]

(promiseオブジェクトが)resolveされる は意味的には一応間違ってはないけど、 日本語的にはこっちのほうが使いやすくて面倒だなー

resolveされた -> その結果 -> promiseオブジェクトのstateがFulFilledとなる

Promise.all は、stateがFulFilledとなったのがキーとして反応するから、resolveされた時というのは多分違う。 けど、resolveされた時という表現自体は間違いではなくて、仕様でもそういう表現出てくる。

A promise is resolved if it is settled or if it has been "locked in" match the state of another promise.

https://github.com/domenic/promises-unwrapping#promise-objects

なので、resolveされたという表現は積極的ではないけど、使っても問題はない感じ。

[azu]

コミットメッセージについて特に何も決めてなかったけど、 conventional-changelog/CONVENTIONS.md at master · ajoslin/conventional-changelog のルールに大体したがって書いている。

write()という独自の記号を増やしてるけど…

ajoslin/conventional-changelog ベースのCHANGELOGを自動生成するために使ってるようなものなので、CHANGELOGに入れたほうがいいようなコミットはchoreではなくてfixを使ったほうがいいとかそれぐらいのイメージでやってる。

feat, write, fix, docs がたしかCHANGELOGにでるコミットの対象

[azu]

https://github.com/azu/promises-book/blob/master/CONTRIBUTE.md

にコミットメッセージを追加した

[azu]

Asciidoctor に依存した書き方を使っていい事を追記した

[azu]

https://github.com/azu/textlint-plugin-asciidoc-loose と textlintを使って簡単にはチェックしてる