跳至主要內容

拼寫、標點符號和格式

避免使用縮寫​

為了與我們的對話風格保持一致，某些縮寫是可以接受的。

  • 包含「is」或「are」的縮寫。例如：it's 和 you're。
  • 但是，請謹慎使用縮寫。

不過，請避免其他縮寫。例如

  • It'll (請使用 "It will")

文字強調​

請謹慎使用文字強調（粗體 和 斜體）。為了保持文件平靜的語氣，並幫助讀者閱讀，請避免大量使用強調和格式化的文字。

斜體和粗體文字可以很好地強調句子中某些部分，以引起讀者的注意。請較少使用粗體文字，且僅當您想要某些文字從整個段落中脫穎而出時使用（以便讀者在「掃描」頁面而不是仔細閱讀時可以看到）。首次引入新概念時，請使用斜體文字。

請勿使用全部大寫字母來強調文字。

如果您不確定是否要強調某些文字，請不要強調。

UI 元素​

對於 GUI 元素（按鈕、下拉式選單等）的名稱，請使用 粗體。並使用與 GUI 中相同的大小寫。例如

  1. 在 **檔案** 選單中，選取 **開啟...**。

避免使用驚嘆號​

為了保持我們平靜的語氣，請勿使用驚嘆號。

例外：在祝賀或歡迎訊息中可以接受，例如：「恭喜 - 您已完成本教學課程！」

將專有名詞大寫並拼寫出來​

雖然您可能會想使用像「Postgres」（而不是官方專有名詞「PostgreSQL」）這樣的縮寫，或者在寫「Javascript」（而不是「JavaScript」）時不注意大小寫，但我們使用專有名詞的官方形式。以下是一些常見的範例：

  • Node.js (而不是 Node 或 Node.JS)
  • JavaScript 和 TypeScript (而不是 JavaScript 和 Typescript 或 JS 和 TS)
  • PostgreSQL (而不是 Postgres 或 Postgresql)
  • MongoDB (而不是 Mongo)
  • GitHub (而不是 Github)
  • 對於 JSON，請參閱特殊情況：JSON

如果您不確定專有名詞的拼寫，請查看其官方網站。

標題和標題​

  • 標題和標題請使用句子大小寫：只有首字母大寫（例外：將專有名詞大寫）
  • 避免使用動名詞（「設定資料庫」，而不是「正在設定資料庫」）
  • 除非需要問號，否則請勿在標題或標題末尾使用標點符號
  • 在標題中使用 code - 這是我們的導覽元素所要求的

表格、項目符號清單和編號清單​

表格和清單通常是呈現資訊最簡潔的方式。請在適當的時候使用這些元素。以下是一些準則

  • 當清單的順序不重要時，請使用項目符號清單（例如，沒有固有順序的資料庫功能列舉）。
  • 僅當清單的順序重要時，才使用編號清單（例如，在提供逐步說明時，其中一個步驟建立在前一個步驟的基礎上）。
  • 使用表格來描述具有許多相似屬性/特性的事物（例如，API 呼叫的參數，它們都具有「名稱」、「類型」，是必要還是可選，並且需要描述）。
  • 對於編號/排序清單和項目符號清單，如果它是完整的句子，請在末尾加上句點。這在排序清單中最常見，其中包含一系列步驟。

連字號​

請根據這些規則使用連字號。

有時，有些術語不清楚是否應該使用連字號。為了力求一致，我們在此列出這些術語。

拼寫時不使用連字號​

  • 使用案例
  • 命令列（當作為名詞引用時：「在命令列上」。當它是形容詞時，請使用連字號：「這個命令列選項...」）
  • 自動格式化
  • 類型安全 (有關「type safe」的指南，請參閱下方)
  • 檔案名稱
  • 編譯時間（當您將其用作名詞時：「... 在編譯時間」。當它是形容詞時，請使用連字號：「這個編譯時間操作...」）

拼寫為一個單字​

  • 自動完成
  • 程式碼庫

類型安全、type safe 和類型安全​

  • 「此程式碼是類型安全的。」 (名詞後的形容詞)
  • 「這是類型安全的程式碼。」 (名詞前的形容詞)
  • 「Prisma ORM 的一個主要功能是類型安全。」 (名詞)

資料來源和 datasource​

  • datasource 區塊
  • 「當您引入新的資料來源時，必須重新產生 Prisma Client」

檔案和檔案類型​

當您引用檔案或檔案類型時，請使用小寫和程式碼格式，並包含點號。如果檔案副檔名在發音時以母音開頭，則使用介詞「an」，否則使用「a」

  • 一個 .jpg 檔案
  • 一個 .xls 檔案
  • 一個 .env 檔案
  • 對於 json 檔案，請參閱特殊情況：JSON

注意：當您引用特定檔案時，請使用檔案名稱中使用的大小寫

  • schema.prisma 檔案

特殊情況：JSON​

  • 當您一般性地引用 JSON 時，請使用全部大寫且不使用程式碼格式
  • 當您引用 Prisma Json API 時，請使用 Json
  • 當您引用 JSON 檔案時，請使用上述格式規則：「一個 .json 檔案」

針對路徑和檔案名稱使用行內程式碼格式​

例如

  • 「預設情況下，產生的 Prisma Client 位於 ./node_modules/.prisma 資料夾中。」
  • 「schema.prisma 檔案位於...」
  • 「若要使用多個 .env 檔案...」

當在文字中引用字串時，請使用行內程式碼格式​

例如

「以下查詢會傳回 email 欄位等於 Sarah 的所有記錄。」

避免過多的程式碼格式​

如果文件有過多特殊格式，可能會很快在視覺上變得混亂。我們的文件具有高度技術性，我們經常引用程式碼片段或出現在使用者程式碼中的技術關鍵字。對於這些關鍵字，我們適當地使用程式碼格式。但是，我們不應使用程式碼格式引用一般技術（例如 JSON）。

例如

Prisma 會自動將 JavaScript 物件（例如，{ extendedPetsData: "none"}）轉換為 JSON。

使用牛津逗號讓清單更清晰​

除了標題之外，請使用牛津逗號。它是用於三個或更多項目清單中倒數第二個項目之後，在「and」或「or」之前的逗號。它使事情更清楚。範例：「... 一位義大利畫家、雕塑家和建築師」。

在少數情況下，牛津逗號可能會使列表變得較不清楚。在這種情況下，盡可能重新排列列表，以使意思明確。

程式碼片段​

介紹所有程式碼片段​

撰寫一個簡短的介紹句子，說明：

  • 程式碼片段的作用
  • 如果適用，連結至參考文件

例如

此 createMany() 查詢執行以下操作：

  • 建立多個 User 記錄
  • 建立多個巢狀 Post 記錄
  • 建立多個巢狀 Category 記錄

盡可能顯示查詢結果​

使用 <CodeWithResult> 元件來顯示查詢和該查詢的結果。

使用 highlight 註解來醒目提示程式碼​

如果您需要在程式碼範例中醒目提示程式碼行，請使用 highlight magic comments。例如：

```prisma
generator client {
  provider        = "prisma-client-js"
  //highlight-next-line
  previewFeatures = ["namedConstraints"]
}
```

格式化程式碼區塊和內嵌程式碼​

在建立和編輯文件時，請使用以下連結作為參考：格式化內嵌程式碼和程式碼區塊。

強調佔位符​

佔位符是技術文件中一個棘手的問題，也是最常見的混淆來源之一，尤其是對於初學者。為了力求一致，Prisma 文件中的佔位符：

  • 以全部大寫字母拼寫
  • 前後綴以兩個底線
  • 使用描述性術語

例如，考慮以下程式碼區塊，其中 __DATABASE_CONNECTION_URL__ 是 PostgreSQL 連線 URL 的佔位符

datasource db {
  provider = "postgresql"
  url      = "__DATABASE_CONNECTION_STRING__"
}

每當您使用佔位符時，請說明如何取得佔位符的值，或連結至說明此內容的其他資源。明確指出這是一個佔位符，必須替換為「真實值」。包含一個真實值可能看起來像什麼的範例

datasource db {
  provider = "postgresql"
  url      = "postgresql://opnmyfngbknppm:XXX@ec2-46-137-91-216.eu-west-1.compute.amazonaws.com:5432/d50rgmkqi2ipus?schema=hello-prisma2"
}

使用表達性變數名稱​

好

const getUsers = (...)
const deleteUsers = (...)

差

const results = (...) // Too generic
const foo = (...) // Too vague

包含有效的程式碼片段​

確保您包含的程式碼片段是實際的範例，如果在呈現的環境中執行，應該會有效。

遵循 Prisma Schema 命名慣例​

當您為範例建立 Prisma Schema 時，請遵循我們建議使用者使用的命名慣例。

在單一程式碼區塊中列出 shell 命令​

當您需要提供一系列 CLI 命令作為讀者的指示時，請使用單一區塊。除非您想為每個步驟提供上下文，否則不要使用列表

差​

  • cd path/to/server
  • docker compose up -d --build
  • ./node_modules/.bin/sequelize db:migrate 或 npx sequelize db:migrate
  • ./node_modules/.bin/sequelize db:seed:all 或 npx sequelize db:seed:all

更好​

cd path/to/server
docker compose up -d --build
./node_modules/.bin/sequelize db:migrate # or `npx sequelize db:migrate`
./node_modules/.bin/sequelize db:seed:all # or `npx sequelize db:seed:all`

或

  1. 導覽至專案目錄：cd path/to/server
  2. 啟動 Docker 容器：docker compose up -d --build
  3. 遷移您的資料庫架構：./node_modules/.bin/sequelize db:migrate 或 npx sequelize db:migrate
  4. 植入資料庫：./node_modules/.bin/sequelize db:seed:all 或 npx sequelize db:seed:all

請勿在程式碼區塊中的 CLI 命令前面加上 $​

為 CLI 命令使用 terminal 語言 meta 字串 - 此類型的程式碼區塊包含 $

```terminal
npm install prisma
```

例如

npm install prisma

使用 npm 作為預設套件管理器​

所有範例都應使用 npm。其他套件管理器選項 (yarn、pnpm、bun) 只有在命令不同時才應使用，且絕不應作為預設值。